metanorma-document 0.2.9 → 0.3.0

data/lib/metanorma/mirror/default_registry.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    # Single source of truth for the default Metanorma → Mirror handler
+    # registrations. `Mirror.default_registry` memoizes a frozen instance
+    # built from here; `Mirror.build_default_registry` returns a fresh
+    # instance each call.
+    #
+    # Adding a new model class to handler mapping = adding one
+    # `register_default` call here. No edits to HandlerRegistry (OCP).
+    module DefaultRegistry
+      class << self
+        def build
+          registry = HandlerRegistry.new
+          register_default(registry)
+          registry
+        end
+
+        private
+
+        def register_default(registry)
+          register_paragraphs(registry)
+          register_blocks(registry)
+          register_lists(registry)
+          register_sections(registry)
+          register_terms(registry)
+          register_structural(registry)
+        end
+
+        def register_paragraphs(registry)
+          registry.register(
+            Metanorma::Document::Components::Paragraphs::ParagraphBlock,
+            Handlers::Paragraph,
+          )
+        end
+
+        def register_blocks(registry)
+          registry.register(
+            Metanorma::Document::Components::Blocks::NoteBlock,
+            Handlers::Note,
+          )
+          registry.register(
+            Metanorma::Document::Components::MultiParagraph::AdmonitionBlock,
+            Handlers::Admonition,
+          )
+          registry.register(
+            Metanorma::Document::Components::AncillaryBlocks::ExampleBlock,
+            Handlers::Example,
+          )
+          registry.register(
+            Metanorma::Document::Components::AncillaryBlocks::FigureBlock,
+            Handlers::Figure,
+          )
+          registry.register(
+            Metanorma::Document::Components::AncillaryBlocks::SourcecodeBlock,
+            Handlers::Sourcecode,
+          )
+          registry.register(
+            Metanorma::Document::Components::AncillaryBlocks::FormulaBlock,
+            Handlers::Formula,
+          )
+          registry.register(
+            Metanorma::Document::Components::MultiParagraph::QuoteBlock,
+            Handlers::Quote,
+          )
+          registry.register(
+            Metanorma::Document::Components::Tables::TableBlock,
+            Handlers::Table,
+          )
+          registry.register(
+            Metanorma::Document::Components::MultiParagraph::ReviewBlock,
+            Handlers::Review,
+          )
+        end
+
+        def register_lists(registry)
+          registry.register(
+            Metanorma::Document::Components::Lists::UnorderedList,
+            Handlers::List,
+            method_name: :bullet,
+          )
+          registry.register(
+            Metanorma::Document::Components::Lists::OrderedList,
+            Handlers::List,
+            method_name: :ordered,
+          )
+          registry.register(
+            Metanorma::Document::Components::Lists::DefinitionList,
+            Handlers::List,
+            method_name: :definition,
+          )
+          registry.register(
+            Metanorma::Document::Components::Lists::ListItem,
+            Handlers::List,
+            method_name: :list_item,
+          )
+        end
+
+        def register_sections(registry)
+          registry.register(
+            Metanorma::StandardDocument::Sections::ClauseSection,
+            Handlers::Section,
+            method_name: :clause,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::AnnexSection,
+            Handlers::Section,
+            method_name: :annex,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::ContentSection,
+            Handlers::Section,
+            method_name: :content_section,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::TermsSection,
+            Handlers::Section,
+            method_name: :terms,
+          )
+          registry.register(
+            Metanorma::IsoDocument::Sections::IsoTermsSection,
+            Handlers::Section,
+            method_name: :terms,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::DefinitionSection,
+            Handlers::Section,
+            method_name: :definitions,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::StandardReferencesSection,
+            Handlers::Section,
+            method_name: :references,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::FloatingTitle,
+            Handlers::Section,
+            method_name: :floating_title,
+          )
+        end
+
+        def register_terms(registry)
+          registry.register(
+            Metanorma::IsoDocument::Terms::IsoTerm,
+            Handlers::Term,
+          )
+        end
+
+        def register_structural(registry)
+          registry.register(
+            Metanorma::StandardDocument::Sections::Preface,
+            Handlers::Structural,
+            method_name: :preface,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::Sections,
+            Handlers::Structural,
+            method_name: :sections,
+          )
+          registry.register(
+            Metanorma::StandardDocument::Sections::BibliographySection,
+            Handlers::Structural,
+            method_name: :bibliography,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handler_registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    class HandlerRegistry
+      Entry = Struct.new(:callable, :concat, :extra_kwargs, keyword_init: true)
+
+      def initialize
+        @handlers = {}
+      end
+
+      def register(model_class, handler, method_name: :call, concat: false,
+                   extra_kwargs: {})
+        callable = resolve_callable(handler, method_name)
+        @handlers[model_class] = Entry.new(
+          callable: callable,
+          concat: concat,
+          extra_kwargs: extra_kwargs,
+        )
+      end
+
+      def registered?(model_class)
+        @handlers.key?(model_class)
+      end
+
+      def entry_for(model_element)
+        @handlers[model_element.class] || ancestor_entry(model_element)
+      end
+
+      def handle(model_element, context:)
+        entry = entry_for(model_element)
+        return HandlerResult.none unless entry
+
+        kwargs = { context: context }.merge(entry.extra_kwargs || {})
+        result = entry.callable.call(model_element, **kwargs)
+        HandlerResult.new(result, concat: entry.concat)
+      end
+
+      private
+
+      def resolve_callable(handler, method_name)
+        return handler if handler.is_a?(Proc)
+        return handler.method(:call) if method_name == :call
+
+        handler.method(method_name)
+      end
+
+      def ancestor_entry(model_element)
+        model_element.class.ancestors.each do |ancestor|
+          next if ancestor == model_element.class
+          break if ancestor == Object
+
+          entry = @handlers[ancestor]
+          return entry if entry
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handler_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    class HandlerResult
+      attr_reader :nodes
+
+      def self.none
+        new(nil, concat: false)
+      end
+
+      def initialize(nodes, concat: false)
+        @nodes = nodes
+        @concat = concat
+      end
+
+      def none?
+        @nodes.nil?
+      end
+
+      def concat?
+        @concat
+      end
+
+      def append_to(content)
+        return content if none?
+
+        if concat?
+          content.concat(Array(@nodes))
+        else
+          content << @nodes
+        end
+        content
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handlers/admonition.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Admonition
+        EXTRA = { type: nil, target: nil, unnumbered: nil }.freeze
+
+        def self.call(element, context:)
+          attrs = Handlers.extract_attrs(element, extra_attrs: EXTRA)
+          content = context.extract_blocks(element)
+
+          Handlers.build_node("admonition", attrs: attrs, content: content)
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handlers/example.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Example
+        EXTRA = { unnumbered: nil, subsequence: nil }.freeze
+
+        def self.call(element, context:)
+          attrs = Handlers.extract_attrs(element, extra_attrs: EXTRA)
+          content = context.extract_named_collections(element,
+                                                      %i[paragraphs formula
+                                                         ul ol quote sourcecode
+                                                         table figure dl])
+
+          Handlers.build_node("example", attrs: attrs, content: content)
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handlers/figure.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Figure
+        def self.call(element, context:)
+          attrs = figure_attrs(element)
+          content = []
+
+          img = SafeAttr.read(element, :image)
+          if img
+            img_attrs = {}
+            src = SafeAttr.read(img, :source)
+            img_attrs[:src] =
+              src && !src.strip.empty? ? src : SafeAttr.read(img, :filename)
+            img_attrs[:alt] = SafeAttr.read(img, :alt)
+            img_attrs[:height] = SafeAttr.read(img, :height)
+            img_attrs[:width] = SafeAttr.read(img, :width)
+            content << Handlers.build_node("image", attrs: img_attrs.compact)
+          end
+
+          subfigures = SafeAttr.read(element, :figure)
+          subfigures&.each do |sub|
+            result = context.registry.handle(sub, context: context)
+            result.append_to(content)
+          end
+
+          notes = SafeAttr.read(element, :note)
+          notes&.each do |n|
+            result = context.registry.handle(n, context: context)
+            result.append_to(content)
+          end
+
+          Handlers.build_node("figure", attrs: attrs, content: content)
+        end
+
+        def self.figure_attrs(element)
+          attrs = {}
+          attrs[:id] = SafeAttr.read(element, :id)
+          attrs[:unnumbered] = SafeAttr.read(element, :unnumbered)
+          attrs[:width] = SafeAttr.read(element, :width)
+          attrs[:align] = SafeAttr.read(element, :align)
+          attrs[:semx_id] = SafeAttr.read(element, :semx_id)
+
+          name = SafeAttr.read(element, :name)
+          attrs[:title] = Handlers.extract_name_text(name) if name
+          attrs.compact
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handlers/formula.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Formula
+        EXTRA = { unnumbered: nil, inequality: nil }.freeze
+
+        def self.call(element, context:)
+          attrs = Handlers.extract_attrs(element, extra_attrs: EXTRA)
+
+          stem = SafeAttr.read(element, :stem)
+          if stem
+            attrs[:stem_type] = SafeAttr.read(stem, :stem_type)
+
+            asciimath = SafeAttr.read(stem, :asciimath)
+            if asciimath&.value && !asciimath.value.strip.empty?
+              attrs[:asciimath] =
+                asciimath.value
+            end
+
+            math = SafeAttr.read(stem, :math)
+            attrs[:mathml] = MathUtil.mathml_from_math(math) if math
+          end
+
+          # Legacy fallback: some older documents store text directly
+          text = SafeAttr.read(element, :text)
+          attrs[:math_text] = Array(text).join if text && !attrs[:asciimath]
+
+          Handlers.build_node("formula", attrs: attrs.compact)
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handlers/inline/catalog.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Inline
+        # Shared declarative table of inline marks whose HTML rendering is
+        # a fixed tag with optional static attrs. Two adapters consume it:
+        #
+        # - RichHtmlRenderer: renders Metanorma XML elements to HTML
+        #   directly (the fallback / attribute-value path).
+        # - Output::HtmlRenderers::MarkRenderers: renders mirror Model marks
+        #   to HTML (the primary SSR path).
+        #
+        # Both adapters must produce visually equivalent HTML for the same
+        # mark type — the table is the single source of truth for the
+        # mark-name to tag-and-attrs mapping. Marks whose attrs vary per
+        # instance (link, xref, eref, span) carry data in mark.attrs and
+        # are not in this table; each adapter keeps custom handlers for
+        # those.
+        module Catalog
+          SIMPLE_WRAPS = {
+            "emphasis" => { tag: :em },
+            "strong" => { tag: :strong },
+            "subscript" => { tag: :sub },
+            "superscript" => { tag: :sup },
+            "code" => { tag: :code },
+            "underline" => { tag: :u },
+            "strike" => { tag: :s },
+            "smallcap" => { tag: :span, style: "font-variant: small-caps" },
+            "concept" => { tag: :span, class: "concept" },
+            "bcp14" => { tag: :span, class: "bcp14" },
+            "footnote" => { tag: :sup, class: "footnote-inline" },
+            "stem" => { tag: :span, class: "stem" },
+          }.freeze
+
+          # XML element classes that render via SIMPLE_WRAPS without
+          # per-instance attrs. Maps element class → mark type (catalog
+          # key). RichHtmlRenderer uses this to dispatch simple elements
+          # through the shared table.
+          SIMPLE_ELEMENTS = {
+            Metanorma::Document::Components::Inline::EmRawElement => "emphasis",
+            Metanorma::Document::Components::Inline::StrongRawElement => "strong",
+            Metanorma::Document::Components::Inline::SubElement => "subscript",
+            Metanorma::Document::Components::Inline::SupElement => "superscript",
+            Metanorma::Document::Components::Inline::TtElement => "code",
+            Metanorma::Document::Components::TextElements::UnderlineElement => "underline",
+            Metanorma::Document::Components::TextElements::StrikeElement => "strike",
+            Metanorma::Document::Components::Inline::SmallCapElement => "smallcap",
+            Metanorma::Document::Components::Inline::Bcp14Element => "bcp14",
+            Metanorma::Document::Components::Inline::ConceptElement => "concept",
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handlers/inline/rich_html_renderer.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Inline
+        # Renders inline Metanorma elements as HTML strings. Used when an HTML
+        # representation of inline content is required (e.g., attribute values,
+        # fallback rendering). All HTML construction goes through
+        # Nokogiri::HTML5::Builder to guarantee well-formed, escaped output.
+        #
+        # Simple-wrap elements (em, strong, sub, sup, code, u, s, smallcap,
+        # bcp14, concept) share their tag-and-attrs mapping with the Model-side
+        # renderer via Inline::Catalog, so the XML→HTML and Model→HTML paths
+        # produce visually equivalent output for the same mark type.
+        module RichHtmlRenderer
+          # Complex element handlers — these have per-instance attrs or
+          # multi-step rendering and bypass the shared Catalog.
+          COMPLEX_RENDERERS = {
+            Metanorma::Document::Components::Inline::StemInlineElement => ->(el) {
+              for_stem(el)
+            },
+            Metanorma::Document::Components::TextElements::StemElement => ->(el) {
+              for_stem(el)
+            },
+            Metanorma::Document::Components::Inline::XrefElement => ->(el) {
+              for_xref(el)
+            },
+            Metanorma::Document::Components::Inline::LinkElement => ->(el) {
+              for_link(el)
+            },
+            Metanorma::Document::Components::Inline::ErefElement => ->(el) {
+              for_eref(el)
+            },
+            Metanorma::Document::Components::Inline::FnElement => ->(el) {
+              for_fn(el)
+            },
+            Metanorma::Document::Components::Inline::SpanElement => ->(el) {
+              for_span(el)
+            },
+            Metanorma::Document::Components::Inline::BrElement => ->(_el) {
+              wrap(&:br)
+            },
+          }.freeze
+
+          def self.extract(element)
+            return "" unless element
+
+            unless element.is_a?(Lutaml::Model::Serializable)
+              return CGI.escapeHTML(element.to_s)
+            end
+
+            parts = []
+            element.each_mixed_content { |node| parts << render_node(node) }
+            result = parts.join.strip
+            result.empty? ? TextExtractor.extract_element_text(element) : result
+          end
+
+          def self.render_node(node)
+            case node
+            when String
+              CGI.escapeHTML(node)
+            when Lutaml::Model::Serializable
+              render_element(node)
+            else
+              ""
+            end
+          end
+
+          def self.render_element(element)
+            complex = COMPLEX_RENDERERS[element.class]
+            return complex.call(element) if complex
+
+            mark_type = Catalog::SIMPLE_ELEMENTS[element.class]
+            return render_simple(mark_type, element) if mark_type
+
+            extract(element)
+          end
+
+          def self.render_simple(mark_type, element)
+            spec = Catalog::SIMPLE_WRAPS[mark_type]
+            attrs = spec.except(:tag)
+            wrap do |d|
+              if attrs.empty?
+                d.public_send(spec[:tag]) { d << raw(extract(element)) }
+              else
+                d.public_send(spec[:tag], attrs) { d << raw(extract(element)) }
+              end
+            end
+          end
+
+          def self.for_stem(element)
+            math = SafeAttr.read(element, :math)
+            return TextExtractor.extract_element_text(element) unless math
+
+            mathml = MathUtil.mathml_from_math(math)
+              .sub(/\s*xmlns(:\w+)?="[^"]*"\s*/, " ")
+              .gsub(/\s+/, " ")
+              .strip
+            spec = Catalog::SIMPLE_WRAPS["stem"]
+            wrap do |d|
+              d.public_send(spec[:tag], spec.except(:tag)) { d << raw(mathml) }
+            end
+          end
+
+          def self.for_xref(element)
+            target = SafeAttr.read(element, :target) || ""
+            label = TextExtractor.extract_formatted_text(element)
+            label = target if label.strip.empty?
+            wrap { |d| d.a(href: "##{target}") { d.text label } }
+          end
+
+          def self.for_link(element)
+            href = SafeAttr.read(element,
+                                 :target) || SafeAttr.read(element, :href) || ""
+            label = TextExtractor.extract_formatted_text(element)
+            wrap { |d| d.a(href: href) { d.text label } }
+          end
+
+          def self.for_eref(element)
+            citeas = SafeAttr.read(element, :citeas) || ""
+            label = TextExtractor.extract_formatted_text(element)
+            wrap { |d| d.a(class: "eref", cite: citeas) { d.text label } }
+          end
+
+          def self.for_fn(element)
+            reference = SafeAttr.read(element, :reference) || ""
+            spec = Catalog::SIMPLE_WRAPS["footnote"]
+            wrap do |d|
+              d.public_send(spec[:tag], spec.except(:tag)) { d.text reference }
+            end
+          end
+
+          def self.for_span(element)
+            cls = SafeAttr.read(element, :class_attr)
+            inner = extract(element)
+            wrap do |d|
+              if cls
+                d.span(class: cls) { d << raw(inner) }
+              else
+                d.span { d << raw(inner) }
+              end
+            end
+          end
+
+          def self.wrap(&)
+            Nokogiri::HTML5::Builder.new(&).doc.root.to_html
+          end
+
+          def self.raw(html_string)
+            Nokogiri::HTML5::DocumentFragment.parse(html_string.to_s)
+          end
+        end
+      end
+    end
+  end
+end