coradoc 1.1.7 → 2.0.2

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

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require_relative 'converter_base'
+
+module Coradoc
+  module Html
+    # Static HTML converter
+    #
+    # Converts CoreModel documents to static HTML5 output.
+    # This converter produces traditional HTML with external or embedded CSS/JS.
+    #
+    # @example Basic usage
+    #   doc = Coradoc.parse_file('document.adoc')
+    #   html = Coradoc::Html::Static.convert(doc)
+    #
+    # @example With configuration
+    #   config = Coradoc::Html::Static::Configuration.new(
+    #     css_theme: :professional,
+    #     include_toc: true,
+    #     theme_toggle: true
+    #   )
+    #   html = Coradoc::Html::Static.convert(doc, config)
+    #
+    # @example Write to file
+    #   Coradoc::Html::Static.to_file(doc, 'output.html', config)
+    class Static < ConverterBase
+      # Configuration for Static HTML output
+      #
+      # Plain Ruby configuration class with accessors and defaults.
+      class Configuration
+        # CSS theme to use (:professional, :academic, :tech)
+        attr_accessor :css_theme
+
+        # How to deliver assets (:embedded, :external)
+        attr_accessor :asset_delivery
+
+        # Whether to include table of contents
+        attr_accessor :include_toc
+
+        # TOC levels to include (1-5)
+        attr_accessor :toc_levels
+
+        # TOC title text
+        attr_accessor :toc_title
+
+        # TOC placement (:auto, :left, :right, :preamble)
+        attr_accessor :toc_placement
+
+        # Whether to enable theme toggle (dark/light mode)
+        attr_accessor :theme_toggle
+
+        # Whether to preserve comments in output
+        attr_accessor :preserve_comments
+
+        # Whether to apply section numbering
+        attr_accessor :section_numbering
+
+        # Maximum section level for numbering
+        attr_accessor :section_numbering_levels
+
+        # Language attribute for HTML
+        attr_accessor :lang
+
+        # Custom meta tags
+        attr_accessor :meta_tags
+
+        # Custom CSS to append
+        attr_accessor :custom_css
+
+        # Whether to embed output (no full HTML document)
+        attr_accessor :embedded
+
+        # Valid CSS themes
+        VALID_CSS_THEMES = %i[professional academic tech].freeze
+
+        # Valid asset delivery methods
+        VALID_ASSET_DELIVERIES = %i[embedded external].freeze
+
+        # Valid TOC placements
+        VALID_TOC_PLACEMENTS = %i[auto left right preamble].freeze
+
+        # Initialize configuration with options
+        #
+        # @param options [Hash] Configuration options
+        def initialize(**options)
+          @css_theme = options[:css_theme] || :professional
+          @asset_delivery = options[:asset_delivery] || :embedded
+          @include_toc = options.fetch(:include_toc, false)
+          @toc_levels = options[:toc_levels] || 2
+          @toc_title = options[:toc_title] || 'Table of Contents'
+          @toc_placement = options[:toc_placement] || :auto
+          @theme_toggle = options.fetch(:theme_toggle, true)
+          @preserve_comments = options.fetch(:preserve_comments, false)
+          @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)
+        end
+
+        # Default configuration
+        #
+        # @return [Configuration] Default configuration instance
+        def self.defaults
+          new
+        end
+
+        # Merge with another configuration or hash
+        #
+        # @param other [Hash, Configuration] Configuration to merge
+        # @return [Configuration] New merged configuration
+        def merge(other)
+          other_hash = other.is_a?(Configuration) ? other.to_h : other.to_h.transform_keys(&:to_sym)
+          self.class.new(**to_h.merge(other_hash))
+        end
+
+        # Convert to hash
+        #
+        # @return [Hash] Configuration as hash
+        def to_h
+          {
+            css_theme: @css_theme,
+            asset_delivery: @asset_delivery,
+            include_toc: @include_toc,
+            toc_levels: @toc_levels,
+            toc_title: @toc_title,
+            toc_placement: @toc_placement,
+            theme_toggle: @theme_toggle,
+            preserve_comments: @preserve_comments,
+            section_numbering: @section_numbering,
+            section_numbering_levels: @section_numbering_levels,
+            lang: @lang,
+            meta_tags: @meta_tags,
+            custom_css: @custom_css,
+            embedded: @embedded
+          }
+        end
+
+        # Validate configuration
+        #
+        # @raise [ConverterBase::ValidationError] if configuration is invalid
+        def validate!
+          unless VALID_CSS_THEMES.include?(@css_theme.to_sym)
+            raise ConverterBase::ValidationError,
+                  "Invalid CSS theme: #{@css_theme}. " \
+                  "Valid themes: #{VALID_CSS_THEMES.join(', ')}"
+          end
+
+          unless VALID_ASSET_DELIVERIES.include?(@asset_delivery.to_sym)
+            raise ConverterBase::ValidationError,
+                  "Invalid asset delivery: #{@asset_delivery}. " \
+                  "Valid options: #{VALID_ASSET_DELIVERIES.join(', ')}"
+          end
+
+          if @include_toc && !VALID_TOC_PLACEMENTS.include?(@toc_placement.to_sym)
+            raise ConverterBase::ValidationError,
+                  "Invalid TOC placement: #{@toc_placement}. " \
+                  "Valid options: #{VALID_TOC_PLACEMENTS.join(', ')}"
+          end
+
+          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
+        end
+
+        # Check if assets should be embedded
+        #
+        # @return [Boolean] true if assets should be embedded
+        def embed_assets?
+          @asset_delivery == :embedded || @embedded
+        end
+
+        # Check if external assets should be linked
+        #
+        # @return [Boolean] true if assets should be linked
+        def link_assets?
+          !embed_assets?
+        end
+      end
+
+      # Convert document to static HTML
+      #
+      # @return [String] Complete HTML5 document or fragment (if embedded mode)
+      def convert
+        # Build options hash for ClassicRenderer
+        options = build_renderer_options
+
+        # Use ClassicRenderer to generate HTML
+        renderer = Html::Theme::ClassicRenderer.new(@document, options)
+
+        if @config.embedded
+          renderer.render
+        else
+          renderer.render_html5
+        end
+      end
+
+      private
+
+      # Build options hash for ClassicRenderer
+      #
+      # @return [Hash] Options for the classic renderer
+      def build_renderer_options
+        # When TOC is enabled with auto placement, default to left sidebar
+        effective_toc_placement = if @config.include_toc && @config.toc_placement == :auto
+                                    :left
+                                  else
+                                    @config.toc_placement
+                                  end
+
+        options = {
+          theme: :classic,
+          css_theme: @config.css_theme.to_s,
+          linkcss: @config.link_assets?,
+          copycss: true,
+          toc: @config.include_toc,
+          toclevels: @config.toc_levels,
+          toc_title: @config.toc_title,
+          toc_placement: effective_toc_placement,
+          theme_toggle: @config.theme_toggle,
+          preserve_comments: @config.preserve_comments,
+          sectnums: @config.section_numbering,
+          sectnumlevels: @config.section_numbering_levels,
+          lang: @config.lang,
+          meta_tags: @config.meta_tags,
+          custom_css: @config.custom_css,
+          embedded: @config.embedded
+        }
+
+        # Handle JavaScript based on asset delivery
+        options[:linkjs] = if @config.embed_assets?
+                             false
+                           else
+                             true
+                           end
+
+        options
+      end
+
+      # Build configuration from options
+      #
+      # @param config [Hash, Configuration] Configuration options
+      # @return [Configuration] Configuration object
+      def build_config(config)
+        case config
+        when Configuration
+          config.validate!
+          config
+        when Hash
+          Configuration.new(**config)
+        else
+          Configuration.defaults
+        end
+      end
+
+      # Output processor interface: unique identifier
+      #
+      # @return [Symbol] Processor identifier
+      def self.processor_id
+        :html_static
+      end
+
+      # Output processor interface: check if this processor handles the file
+      #
+      # @param filename [String] Output filename
+      # @return [Boolean] true if this processor can handle the file
+      def self.processor_match?(filename)
+        filename.downcase.end_with?('.html', '.htm')
+      end
+
+      # Output processor interface: execute the conversion
+      #
+      # @param input [Hash] Input from the converter (contains document)
+      # @param options [Hash] Output options
+      # @return [Hash] Hash with nil => HTML output
+      def self.processor_execute(input, options = {})
+        # Handle hash input from converter pipeline
+        document = input.is_a?(Hash) ? (input[:document] || input.values.first) : input
+        html = convert(document, options)
+        # Return in format expected by converter (hash with filename => content)
+        { nil => html }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Coradoc
+  module Html
+    # Configuration for the Liquid template system
+    #
+    # This class manages template directories and provides utilities
+    # for template discovery and customization.
+    #
+    # @example Global configuration
+    #   Coradoc::Html.configure do |config|
+    #     config.template_dirs = ["/path/to/custom/templates"]
+    #   end
+    #
+    # @example Per-render configuration
+    #   Coradoc::Html.serialize(document, template_dirs: ["/custom/templates"])
+    #
+    class TemplateConfig
+      # Default template directory within the gem
+      DEFAULT_TEMPLATE_DIR = Pathname.new(File.join(
+                                            File.dirname(__FILE__), 'templates', 'core_model'
+                                          )).freeze
+
+      # @return [Array<Pathname>] List of user-provided template directories
+      attr_accessor :template_dirs
+
+      # Initialize a new configuration
+      #
+      # @param template_dirs [Array<String, Pathname>] Custom template directories
+      def initialize(template_dirs: [])
+        @template_dirs = Array(template_dirs).map { |dir| Pathname.new(dir) }
+      end
+
+      # Get all template directories (user + default)
+      #
+      # @return [Array<Pathname>] All template directories in search order
+      def all_template_dirs
+        @template_dirs + [DEFAULT_TEMPLATE_DIR]
+      end
+
+      # List all available default templates
+      #
+      # @return [Array<Symbol>] List of template names (without .liquid extension)
+      def self.available_templates
+        @available_templates ||= begin
+          return [] unless DEFAULT_TEMPLATE_DIR.exist?
+
+          DEFAULT_TEMPLATE_DIR
+            .glob('*.liquid')
+            .map { |f| f.basename('.liquid').to_s.to_sym }
+            .sort
+        end
+      end
+
+      # Get the path to a specific default template
+      #
+      # @param name [Symbol, String] Template name (e.g., :bibliography)
+      # @return [Pathname, nil] Path to the template file, or nil if not found
+      def self.template_path_for(name)
+        path = DEFAULT_TEMPLATE_DIR.join("#{name}.liquid")
+        path.exist? ? path : nil
+      end
+
+      # Check if a template exists
+      #
+      # @param name [Symbol, String] Template name
+      # @return [Boolean] True if template exists in any directory
+      def template_exists?(name)
+        all_template_dirs.any? do |dir|
+          dir.join("#{name}.liquid").exist?
+        end
+      end
+
+      # Find a template by name
+      #
+      # @param name [Symbol, String] Template name
+      # @return [Pathname, nil] Path to the first matching template
+      def find_template(name)
+        all_template_dirs.each do |dir|
+          path = dir.join("#{name}.liquid")
+          return path if path.exist?
+        end
+        nil
+      end
+
+      # Reset configuration to defaults
+      #
+      # @return [void]
+      def reset!
+        @template_dirs = []
+      end
+
+      # Create a copy of this configuration with additional directories
+      #
+      # @param additional_dirs [Array<String, Pathname>] Extra directories
+      # @return [TemplateConfig] New configuration with merged directories
+      def with_dirs(additional_dirs)
+        self.class.new(
+          template_dirs: @template_dirs + Array(additional_dirs).map { |d| Pathname.new(d) }
+        )
+      end
+    end
+
+    # Module-level configuration storage
+    class << self
+      # Get the global configuration
+      #
+      # @return [TemplateConfig] The global configuration
+      def configuration
+        @configuration ||= TemplateConfig.new
+      end
+
+      # Configure the template system
+      #
+      # @yield [TemplateConfig] Yields the configuration object
+      # @return [void]
+      #
+      # @example
+      #   Coradoc::Html.configure do |config|
+      #     config.template_dirs = ["/path/to/templates"]
+      #   end
+      def configure
+        yield(configuration) if block_given?
+      end
+
+      # Reset configuration to defaults
+      #
+      # @return [void]
+      def reset_configuration!
+        @configuration = nil
+      end
+
+      # List all available default templates
+      #
+      # @return [Array<Symbol>] List of template names
+      def available_templates
+        TemplateConfig.available_templates
+      end
+
+      # Get the path to a default template
+      #
+      # @param name [Symbol, String] Template name
+      # @return [Pathname, nil] Path to template or nil
+      def template_path_for(name)
+        TemplateConfig.template_path_for(name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'liquid'
+
+module Coradoc
+  module Html
+    # Liquid filters for template rendering
+    module TemplateFilters
+      # Render a CoreModel element by looking up its template
+      #
+      # Usage in templates:
+      #   {{ child | render_element }}
+      #   {% for item in children %}{{ item | render_element }}{% endfor %}
+      #
+      def render_element(input, renderer = nil)
+        return '' if input.nil?
+        return input.map { |i| render_element(i, renderer) }.join("\n") if input.is_a?(Array)
+
+        # Get the renderer from context registers
+        renderer ||= @context.registers[:renderer]
+
+        # If input is a Liquid::Drop, extract the original model object.
+        # Liquid::Drop stores the wrapped object as @object with no public
+        # reader — this is the only way to unwrap it.
+        original = if input.is_a?(::Liquid::Drop)
+                     input.instance_variable_get(:@object)
+                   else
+                     input
+                   end
+
+        # Renderer is always a Coradoc::Html::Renderer which has a render method
+        renderer.render(original)
+      end
+
+      # Escape HTML entities
+      def escape_html(input)
+        input.to_s
+             .gsub(/&/, '&')
+             .gsub(/</, '&lt;')
+             .gsub(/>/, '&gt;')
+             .gsub(/"/, '&quot;')
+             .gsub(/'/, '&#39;')
+      end
+
+      # Escape HTML attribute values
+      def escape_attr(input)
+        input.to_s
+             .gsub(/&/, '&amp;')
+             .gsub(/"/, '&quot;')
+             .gsub(/</, '&lt;')
+             .gsub(/>/, '&gt;')
+      end
+    end
+  end
+end
+
+# Register filters with Liquid (using the non-deprecated API)
+Liquid::Environment.default.register_filter(Coradoc::Html::TemplateFilters)

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'liquid'
+require 'pathname'
+
+module Coradoc
+  module Html
+    # Locates Liquid templates from filesystem with fallback support
+    #
+    # This class implements a template lookup algorithm:
+    # 1. Check user's template directories in order (first match wins)
+    # 2. Fall back to default templates if not found
+    # 3. Return nil if no template found (caller decides fallback)
+    #
+    # @example Basic usage
+    #   locator = TemplateLocator.new(
+    #     user_dirs: ["/path/to/templates"],
+    #     default_dir: "/default/templates"
+    #   )
+    #   locator.find("bibliography") # => "/path/to/templates/bibliography.liquid"
+    #
+    class TemplateLocator
+      # Default template subdirectory within each template root
+      CORE_MODEL_DIR = 'core_model'
+
+      attr_reader :user_dirs, :default_dir
+
+      # Initialize the locator
+      #
+      # @param user_dirs [Array<String>] User template directories (checked first)
+      # @param default_dir [String] Default templates directory (fallback)
+      def initialize(user_dirs: [], default_dir: nil)
+        @user_dirs = Array(user_dirs).map { |d| Pathname.new(d) }
+        @default_dir = default_dir ? Pathname.new(default_dir) : default_template_dir
+        @cache = {}
+      end
+
+      # Find a template by type name
+      #
+      # @param type_name [String] The template type (e.g., "bibliography", "section")
+      # @return [Pathname, nil] Path to template file or nil if not found
+      def find(type_name)
+        return @cache[type_name] if @cache.key?(type_name)
+
+        # First check user directories
+        @user_dirs.each do |dir|
+          template_path = dir / CORE_MODEL_DIR / "#{type_name}.liquid"
+          if template_path.exist?
+            @cache[type_name] = template_path
+            return template_path
+          end
+        end
+
+        # Then check default directory
+        if @default_dir
+          template_path = @default_dir / "#{type_name}.liquid"
+          if template_path.exist?
+            @cache[type_name] = template_path
+            return template_path
+          end
+        end
+
+        @cache[type_name] = nil
+        nil
+      end
+
+      # Check if a template exists (without loading it)
+      #
+      # @param type_name [String] The template type
+      # @return [Boolean] True if template exists
+      def exists?(type_name)
+        !find(type_name).nil?
+      end
+
+      # Get all available template types
+      #
+      # @return [Array<String>] List of available template names
+      def available_templates
+        types = Set.new
+
+        # Collect from user directories
+        @user_dirs.each do |dir|
+          core_model_path = dir / CORE_MODEL_DIR
+          next unless core_model_path.exist? && core_model_path.directory?
+
+          core_model_path.glob('*.liquid') do |f|
+            types.add(f.basename('.liquid').to_s)
+          end
+        end
+
+        # Collect from default directory
+        if @default_dir&.exist? && @default_dir.directory?
+          @default_dir.glob('*.liquid') do |f|
+            types.add(f.basename('.liquid').to_s)
+          end
+        end
+
+        types.to_a.sort
+      end
+
+      # Get the default template directory path
+      #
+      # @return [Pathname] Path to default templates
+      def default_template_dir
+        Pathname.new(File.join(File.dirname(__FILE__), 'templates', CORE_MODEL_DIR))
+      end
+
+      # Clear the template cache (useful when template directories change)
+      def clear_cache
+        @cache.clear
+      end
+    end
+  end
+end

data/coradoc-html/lib/coradoc/html/templates/core_model/annotation_block.liquid

@@ -0,0 +1,20 @@
+{%- comment -%}
+Annotation block template (admonition/NOTE, tip, warning, caution)
+
+Handles Coradoc::CoreModel::AnnotationBlock with types:
+  NOTE, TIP, WARNING, CAUTION, IMPORTANT, INFO
+  TODO: Todo items (checked first)
+  WARNING: Watches for broken refs in paragraphs or lists.
+{%- endcomment -%}
+
+{%- assign type_class = annotation_type | downcase | at_least:1 | capitalize - -%}
+<div id="{{ id }}" class="admonition admonition-{{ style }}">
+  {% if title %}
+    <div class="admonition-title">{{ title }}</div>
+  {% endif %}
+  <div class="admonition-content">
+    {% for item in content %}
+      {{ item | render_element: renderer }}
+    {% endfor %}
+  </div>
+</div>

data/coradoc-html/lib/coradoc/html/templates/core_model/bibliography.liquid

@@ -0,0 +1,16 @@
+{%- comment -%}
+  Bibliography section template for CoreModel::Bibliography
+  Renders a bibliography section with optional title and list of entries
+{%- endcomment -%}
+<section id="{{ id }}" class="bibliography">
+  {% if title %}
+    {%- assign heading_level = level | default: 2 -%}
+    {%- capture heading_tag -%}h{{ heading_level }}{%- endcapture -%}
+    <{{ heading_tag }}>{{ title }}</{{ heading_tag }}>
+  {% endif %}
+  <div class="bibliography-entries">
+    {% for entry in entries %}
+      {{ entry | render_element }}
+    {% endfor %}
+  </div>
+</section>

data/coradoc-html/lib/coradoc/html/templates/core_model/bibliography_entry.liquid

@@ -0,0 +1,44 @@
+{%- comment -%}
+Bibliography entry template
+
+Renders a single bibliography reference with proper ISO document ID formatting.
+{%- endcomment -%}
+
+{%- assign anchor = anchor_name | default: "" -%}
+{%- assign doc_id = document_id | default: "" | strip -%}
+{%- assign ref = ref_text | default: "" | strip -%}
+
+<p id="{{ anchor }}" class="bibliography-entry NormRef">
+  {%- if doc_id contains "ISO" -%}
+    {%- assign cleaned_id = doc_id | remove: "ISO " | strip -%}
+    <span class="stdpublisher">ISO </span>
+
+    {%- if cleaned_id contains ":" -%}
+      {%- assign parts = cleaned_id | split: ":" -%}
+      {%- assign num_part = parts[0] -%}
+      {%- assign year = parts[1] -%}
+
+      {%- if num_part contains "-" -%}
+        {%- assign num_and_part = num_part | split: "-" -%}
+        <span class="stddocNumber">{{ num_and_part[0] }}</span><span class="stddocPart">-{{ num_and_part[1] }}</span>
+      {%- else -%}
+        <span class="stddocNumber">{{ num_part }}</span>
+      {%- endif -%}
+
+      <span class="stddocYear">:{{ year }}</span>
+    {%- elsif cleaned_id contains "-" -%}
+      {%- assign num_and_part = cleaned_id | split: "-" -%}
+      <span class="stddocNumber">{{ num_and_part[0] }}</span><span class="stddocPart">-{{ num_and_part[1] }}</span>
+    {%- else -%}
+      <span class="stddocNumber">{{ cleaned_id }}</span>
+    {%- endif -%}
+  {%- else -%}
+    {%- if doc_id != "" -%}
+      {{ doc_id }}
+    {%- endif -%}
+  {%- endif -%}
+
+  {%- if ref != "" -%}
+    <i><span class="stddocTitle">{{ ref }}</span></i>
+  {%- endif -%}
+</p>