coradoc-html 1.1.7

data/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/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/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/lib/coradoc/html/theme/base.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require 'coradoc/html/base'
+
+module Coradoc
+  module Html
+    module Theme
+      # Abstract base class for all HTML themes
+      #
+      # This class defines the interface that all theme renderers must implement.
+      # Themes are responsible for converting Coradoc document models to HTML output.
+      #
+      # @abstract Subclass and implement {#render} to create a custom theme
+      class Base
+        attr_reader :document, :options
+
+        # Initialize a new theme instance
+        #
+        # @param document [Coradoc::CoreModel::StructuralElement] The document to render
+        # @param options [Hash] Rendering options
+        def initialize(document, options = {})
+          @document = document
+          @options = options
+        end
+
+        # Render the document to HTML
+        #
+        # This method must be implemented by subclasses.
+        #
+        # @abstract
+        # @return [String] The rendered HTML content
+        def render
+          raise NotImplementedError,
+                "#{self.class.name} must implement #render method"
+        end
+
+        # Render the complete HTML5 document
+        #
+        # @return [String] Complete HTML5 document
+        def render_html5
+          html_body = render
+          build_html5_document(html_body)
+        end
+
+        # Get the theme name
+        #
+        # @return [Symbol] Theme name (e.g., :classic, :modern)
+        def theme_name
+          @theme_name ||= self.class.name.split('::').last
+                              .gsub(/Renderer$/, '')
+                              .downcase
+                              .to_sym
+        end
+
+        # Check if this theme supports a specific feature
+        #
+        # @param feature [Symbol] Feature to check (e.g., :dark_mode, :interactive_toc)
+        # @return [Boolean] true if the feature is supported
+        def supports?(feature)
+          supported_features.include?(feature)
+        end
+
+        # List of features supported by this theme
+        #
+        # Subclasses can override to declare supported features.
+        #
+        # @return [Array<Symbol>] List of supported features
+        def supported_features
+          []
+        end
+
+        protected
+
+        # Build complete HTML5 document
+        #
+        # @param body_html [String] HTML body content
+        # @return [String] Complete HTML5 document
+        def build_html5_document(body_html)
+          lang = @options[:lang] || 'en'
+          body_classes = build_body_classes
+
+          <<~HTML
+            <!DOCTYPE html>
+            <html lang="#{lang}">
+            <head>
+            #{build_head_content}
+            </head>
+            <body#{body_classes}>
+            #{body_html}
+            </body>
+            </html>
+          HTML
+        end
+
+        # Build HTML head content
+        #
+        # @return [String] Head section HTML
+        def build_head_content
+          parts = []
+          parts << build_meta_tags
+          parts << build_title_tag
+          parts << build_css_tags
+          parts << build_script_tags
+          parts.compact.reject(&:empty?).join("\n")
+        end
+
+        # Build meta tags
+        #
+        # @return [String] Meta tags HTML
+        def build_meta_tags
+          meta = []
+          meta << '  <meta charset="UTF-8">'
+          meta << '  <meta name="viewport" content="width=device-width, initial-scale=1.0">'
+
+          # Author meta tag
+          if @options[:author]
+            author = escape_attr(@options[:author])
+            meta << %(  <meta name="author" content="#{author}">)
+          end
+
+          # Description meta tag
+          if @options[:description]
+            description = escape_attr(@options[:description])
+            meta << %(  <meta name="description" content="#{description}">)
+          end
+
+          # Keywords meta tag
+          if @options[:keywords]
+            keywords = escape_attr(@options[:keywords])
+            meta << %(  <meta name="keywords" content="#{keywords}">)
+          end
+
+          # Generator meta tag with version
+          meta << %(  <meta name="generator" content="Coradoc #{Coradoc::VERSION}">)
+
+          # Generation timestamp
+          meta << %(  <meta name="generated" content="#{Time.now.utc.iso8601}">)
+
+          # Custom meta tags
+          if @options[:meta_tags].is_a?(Hash)
+            @options[:meta_tags].each do |name, content|
+              meta << %(  <meta name="#{escape_attr(name)}" content="#{escape_attr(content)}">)
+            end
+          end
+
+          meta.join("\n")
+        end
+
+        # Build title tag
+        #
+        # @return [String] Title tag HTML
+        def build_title_tag
+          title = extract_document_title
+          "  <title>#{escape_html(title)}</title>"
+        end
+
+        # Extract document title
+        #
+        # @return [String] Document title
+        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
+
+        # Extract text from content (array of inline elements)
+        #
+        # @param content [Array] Content elements
+        # @return [String] Extracted text
+        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.text
+          else
+            content.to_s
+          end
+        end
+
+        # Build body classes
+        #
+        # @return [String] Body class attribute
+        def build_body_classes
+          classes = []
+          classes << "theme-#{theme_name}"
+
+          classes.empty? ? '' : %( class="#{classes.join(' ')}")
+        end
+
+        # Build CSS tags
+        #
+        # @return [String] CSS link or style tags
+        def build_css_tags
+          ''
+        end
+
+        # Build script tags
+        #
+        # @return [String] Script tags
+        def build_script_tags
+          ''
+        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
+end