metanorma-mirror 1.0.0

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Structural
+        def self.preface(element, context:)
+          attrs = {}
+          attrs[:semx_id] = SafeAttr.read(element, :semx_id)
+          attrs[:displayorder] = SafeAttr.read(element, :displayorder)
+
+          content = []
+          %i[abstract foreword introduction acknowledgements
+             executivesummary].each do |attr|
+            child = SafeAttr.read(element, attr)
+            next unless child
+
+            result = context.registry.handle(child, context: context)
+            result.append_to(content)
+          end
+
+          element_content = SafeAttr.read(element, :content)
+          Array(element_content).each do |child|
+            result = context.registry.handle(child, context: context)
+            result.append_to(content)
+          end
+
+          Handlers.build_node("preface", attrs: attrs.compact, content: content)
+        end
+
+        def self.sections(element, context:)
+          attrs = {}
+          attrs[:semx_id] = SafeAttr.read(element, :semx_id)
+          attrs[:displayorder] = SafeAttr.read(element, :displayorder)
+
+          content = []
+          %i[clause terms definitions references floating_title].each do |attr|
+            collection = SafeAttr.read(element, attr)
+            next unless collection
+
+            Array(collection).each do |child|
+              result = context.registry.handle(child, context: context)
+              result.append_to(content)
+            end
+          end
+
+          Handlers.build_node("sections", attrs: attrs.compact,
+                                          content: content)
+        end
+
+        def self.bibliography(element, context:)
+          attrs = {}
+          attrs[:semx_id] = SafeAttr.read(element, :semx_id)
+
+          content = []
+          refs = SafeAttr.read(element, :references)
+          Array(refs).each do |ref|
+            result = context.registry.handle(ref, context: context)
+            result.append_to(content)
+          end
+
+          Handlers.build_node("bibliography", attrs: attrs.compact,
+                                              content: content)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      # SVG image map: a wrapped figure plus the href-overwriting
+      # targets that bind the SVG's own links to document anchors.
+      # Duck-typed over SafeAttr reads — zero model constants.
+      module Svgmap
+        REFERENCE_KINDS = %i[xref link eref].freeze
+
+        def self.call(element, context:)
+          attrs = {
+            id: SafeAttr.read(element, :id),
+            semx_id: SafeAttr.read(element, :semx_id),
+            links: link_map(element),
+          }.compact
+          content = figure_content(element, context)
+          Handlers.build_node("svgmap", attrs: attrs, content: content)
+        end
+
+        def self.figure_content(element, context)
+          content = []
+          Array(SafeAttr.read(element, :figure)).each do |fig|
+            context.registry.handle(fig, context: context).append_to(content)
+          end
+          content
+        end
+
+        def self.link_map(element)
+          links = {}
+          Array(SafeAttr.read(element, :target)).each do |target|
+            href = SafeAttr.read(target, :href)
+            links[href] = reference_of(target) if href && !href.empty?
+          end
+          links.empty? ? nil : links
+        end
+
+        def self.reference_of(carrier)
+          REFERENCE_KINDS.each do |kind|
+            ref = SafeAttr.read(carrier, kind)
+            next if ref.nil?
+
+            return SafeAttr.read(ref, :target) ||
+                SafeAttr.read(ref, :bibitemid)
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Table
+        def self.call(element, context:)
+          attrs = table_attrs(element)
+          content = []
+
+          thead = SafeAttr.read(element, :thead)
+          if thead
+            rows = extract_rows(thead, context:)
+            unless rows.empty?
+              content << Handlers.build_node("table_head",
+                                             content: rows)
+            end
+          end
+
+          tbody = SafeAttr.read(element, :tbody)
+          if tbody
+            rows = extract_rows(tbody, context:)
+            unless rows.empty?
+              content << Handlers.build_node("table_body",
+                                             content: rows)
+            end
+          end
+
+          tfoot = SafeAttr.read(element, :tfoot)
+          if tfoot
+            rows = extract_rows(tfoot, context:)
+            unless rows.empty?
+              content << Handlers.build_node("table_foot",
+                                             content: rows)
+            end
+          end
+
+          Handlers.build_node("table", attrs: attrs, content: content)
+        end
+
+        def self.extract_rows(table_section, context:)
+          Array(table_section.tr).map do |tr|
+            cells = Array(tr.td).map { |td| build_cell(td, context:) }
+            Array(tr.th).each { |th| cells << build_cell(th, context:) }
+
+            row_attrs = {}
+            row_attrs[:id] = SafeAttr.read(tr, :id)
+            Handlers.build_node("table_row", attrs: row_attrs.compact,
+                                             content: cells)
+          end
+        end
+
+        def self.build_cell(cell, context:)
+          attrs = {}
+          attrs[:colspan] = SafeAttr.read(cell, :colspan)
+          attrs[:rowspan] = SafeAttr.read(cell, :rowspan)
+          attrs[:align] = SafeAttr.read(cell, :align)
+          attrs[:valign] = SafeAttr.read(cell, :valign)
+
+          content = Inline.extract_inline(cell, context:)
+
+          Handlers.build_node("table_cell", attrs: attrs.compact,
+                                            content: content)
+        end
+
+        def self.table_attrs(element)
+          attrs = {}
+          attrs[:id] = SafeAttr.read(element, :id)
+          attrs[:width] = SafeAttr.read(element, :width)
+          attrs[:align] = SafeAttr.read(element, :align)
+          attrs[:unnumbered] = SafeAttr.read(element, :unnumbered)
+          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/term.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      module Term
+        def self.call(element, context:)
+          attrs = {}
+          attrs[:id] = SafeAttr.read(element, :id)
+          attrs[:anchor] = SafeAttr.read(element, :anchor)
+
+          fmt_name = SafeAttr.read(element, :fmt_name)
+          if fmt_name
+            number = Inline.extract_formatted_text(fmt_name)
+            attrs[:number] = number unless number.empty?
+          end
+
+          content = []
+
+          # Term name from fmt_preferred paragraphs
+          extract_fmt_paragraphs(element, :fmt_preferred, content, context)
+
+          # Definition from fmt_definition → semx → p
+          fmt_def = SafeAttr.read(element, :fmt_definition)
+          if fmt_def
+            extract_semx_paragraphs(fmt_def, content, context)
+          end
+
+          # Source from fmt_termsource
+          fmt_ts_list = SafeAttr.read(element, :fmt_termsource)
+          if fmt_ts_list && !fmt_ts_list.empty?
+            source_text = Inline.extract_formatted_text(fmt_ts_list.first)
+            unless source_text.empty?
+              content << Handlers.build_node("paragraph",
+                                             attrs: { class: "source" },
+                                             content: [context.text_node(source_text)])
+            end
+          end
+
+          # Term notes
+          SafeAttr.read(element, :termnote)&.each do |tn|
+            note_attrs = { id: SafeAttr.read(tn, :id) }
+            fn = SafeAttr.read(tn, :fmt_name)
+            if fn
+              num = Inline.extract_formatted_text(fn)
+              note_attrs[:number] = num unless num.empty?
+            end
+            note_content = context.extract_named_collections(tn, %i[p ul ol dl])
+            content << Handlers.build_node("note", attrs: note_attrs.compact,
+                                                   content: note_content)
+          end
+
+          # Term examples
+          SafeAttr.read(element, :termexample)&.each do |te|
+            ex_attrs = { id: SafeAttr.read(te, :id) }
+            ex_content = context.extract_named_collections(te, %i[p ul ol dl])
+            content << Handlers.build_node("example", attrs: ex_attrs.compact,
+                                                      content: ex_content)
+          end
+
+          # Nested terms
+          SafeAttr.read(element, :term)&.each do |t|
+            result = context.registry.handle(t, context: context)
+            result.append_to(content)
+          end
+
+          Handlers.build_node("term", attrs: attrs.compact, content: content)
+        end
+
+        def self.extract_fmt_paragraphs(element, attr_name, content, context)
+          fmt_list = SafeAttr.read(element, attr_name)
+          return unless fmt_list
+
+          fmt_list.each do |fmt_el|
+            ps = SafeAttr.read(fmt_el, :p)
+            next unless ps
+
+            ps.each do |p|
+              result = context.registry.handle(p, context: context)
+              result.append_to(content)
+            end
+          end
+        end
+
+        # fmt_definition wraps content in semx elements → extract p from semx
+        def self.extract_semx_paragraphs(fmt_def, content, context)
+          semx_list = SafeAttr.read(fmt_def, :semx)
+          return unless semx_list
+
+          Array(semx_list).each do |s|
+            SafeAttr.read(s, :p)&.each do |p|
+              result = context.registry.handle(p, context: context)
+              result.append_to(content)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/handlers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      autoload :Paragraph, "#{__dir__}/handlers/paragraph"
+      autoload :Section, "#{__dir__}/handlers/section"
+      autoload :List, "#{__dir__}/handlers/list"
+      autoload :Table, "#{__dir__}/handlers/table"
+      autoload :Figure, "#{__dir__}/handlers/figure"
+      autoload :Svgmap, "#{__dir__}/handlers/svgmap"
+      autoload :Imagemap, "#{__dir__}/handlers/imagemap"
+      autoload :Sourcecode, "#{__dir__}/handlers/sourcecode"
+      autoload :Admonition, "#{__dir__}/handlers/admonition"
+      autoload :Formula, "#{__dir__}/handlers/formula"
+      autoload :Example, "#{__dir__}/handlers/example"
+      autoload :Note, "#{__dir__}/handlers/note"
+      autoload :Quote, "#{__dir__}/handlers/quote"
+      autoload :Review, "#{__dir__}/handlers/review"
+      autoload :Inline, "#{__dir__}/handlers/inline"
+      autoload :Structural, "#{__dir__}/handlers/structural"
+      autoload :Term, "#{__dir__}/handlers/term"
+
+      COMMON_ATTRS = %i[id semx_id].freeze
+
+      def self.build_node(type, attrs: {}, content: [])
+        if content.nil? || content.empty?
+          Model::Leaf.new(type: type, attrs: attrs)
+        else
+          Model::Container.new(type: type, attrs: attrs, content: content)
+        end
+      end
+
+      def self.build_text(text, marks: [])
+        Model::Text.new(text: text, marks: marks)
+      end
+
+      def self.build_mark(type, attrs: {})
+        Model::Mark.new(type: type, attrs: attrs)
+      end
+
+      def self.extract_attrs(element, extra_attrs: {})
+        attrs = {}
+        COMMON_ATTRS.each do |attr|
+          attrs[attr] = SafeAttr.read(element, attr)
+        end
+        extra_attrs.each do |attr, source_attr|
+          attrs[attr] = SafeAttr.read(element, source_attr || attr)
+        end
+        attrs.compact
+      end
+
+      def self.extract_name_text(name)
+        Inline::TextExtractor.extract_name_text(name)
+      end
+
+      def self.extract_bibdata_title(bibdata)
+        Metadata.title_from_bibdata(bibdata)
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/id_strategy/positional.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module IdStrategy
+      # Assign positional IDs (sec-X.Y.Z, table-N, fig-N, anx-X) to elements
+      # that have UUID IDs. Elements with author-assigned explicit IDs are
+      # preserved. Cross-reference targets are translated to use the new IDs.
+      #
+      # Positional IDs are derived from the element's resolved section number
+      # (the "number" attribute on the presentation XML element), which
+      # represents the document's structural position.
+      #
+      # Example:
+      #   UUID element with number "5.4" → id: "sec-5.4"
+      #   UUID element with number "A.2"  → id: "anx-A.2"
+      #   Explicit id "sec-3.1.3.4"       → id: "sec-3.1.3.4" (unchanged)
+      class Positional < Base
+        @categories = {}
+
+        class << self
+          # Registry of Metanorma model classes → positional-ID category
+          # (:section, :annex, :figure, :table). Adding new flavors or new
+          # model types requires only a new register_category call — no
+          # edits to derive/element_category (OCP).
+          def categories
+            @categories
+          end
+
+          def register_category(model_class, category)
+            categories[model_class] = category
+            self
+          end
+
+          def unregister_category(model_class)
+            categories.delete(model_class)
+            self
+          end
+
+          def category_for(element)
+            return categories[element.class] if categories.key?(element.class)
+
+            categories.each do |klass, category|
+              return category if element.is_a?(klass)
+            end
+            nil
+          end
+        end
+
+        def initialize
+          @id_map = {}
+        end
+
+        def assign_id(element)
+          raw = raw_id(element)
+          return raw unless uuid?(raw)
+
+          positional = derive(element)
+          return raw unless positional
+
+          @id_map[raw] = positional
+          positional
+        end
+
+        def finalize!(document)
+          translate_targets(document)
+          document
+        end
+
+        private
+
+        def raw_id(element)
+          SafeAttr.read(element, :id)
+        end
+
+        def uuid?(id)
+          id&.start_with?("_")
+        end
+
+        def derive(element)
+          number = extract_number(element)
+          return nil unless number && !number.strip.empty?
+
+          case self.class.category_for(element)
+          when :section
+            number.match?(/\A[\d.]+\z/) ? "sec-#{number}" : nil
+          when :annex
+            number.match?(/\A[A-Z]/) ? "anx-#{number}" : nil
+          when :figure
+            "fig-#{number}"
+          when :table
+            "table-#{number}"
+          end
+        end
+
+        def extract_number(element)
+          number = SafeAttr.read(element, :number)
+          return number if number && !number.strip.empty?
+
+          attrs = element.class.attributes
+          return nil unless attrs.key?(:fmt_title)
+
+          fmt_title = element.fmt_title
+          return nil unless fmt_title
+
+          parts = collect_autonum_text(fmt_title)
+          parts.empty? ? nil : parts.join(".")
+        end
+
+        def collect_autonum_text(node)
+          parts = []
+          attrs = node.class.attributes
+
+          if attrs.key?(:semx) && node.semx
+            node.semx.each do |s|
+              next unless s.element_attr == "autonum"
+
+              text = s.text&.join
+              parts << text if text && !text.empty?
+            end
+          end
+
+          if attrs.key?(:span) && node.span
+            node.span.each { |sp| parts.concat(collect_autonum_text(sp)) }
+          end
+
+          parts
+        end
+
+        def translate_targets(node)
+          case node
+          when Model::Text
+            node.marks.each { |mark| translate_mark_target(mark) }
+          when Model::Container
+            node.content.each { |child| translate_targets(child) }
+          end
+        end
+
+        def translate_mark_target(mark)
+          return unless mark.type == "xref"
+
+          target = mark["target"]
+          return unless target
+
+          translated = @id_map[target]
+          mark["target"] = translated if translated
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/id_strategy/preserve.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module IdStrategy
+      # Preserve all IDs as-is (default behavior).
+      # UUID elements keep their UUID IDs. Explicit IDs are unchanged.
+      class Preserve < Base
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/id_strategy.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module IdStrategy
+      autoload :Preserve, "#{__dir__}/id_strategy/preserve"
+      autoload :Positional, "#{__dir__}/id_strategy/positional"
+
+      # Base class for ID assignment strategies.
+      #
+      # A strategy controls how element IDs are assigned during mirror
+      # generation. Subclasses override assign_id and finalize!.
+      #
+      # assign_id(element)  — called per element during node construction
+      # finalize!(document) — called once after the full mirror tree is built
+      #
+      # Adding a new strategy = adding a new class. No changes to handlers
+      # or the converter (OCP).
+      class Base
+        # Returns the ID string to assign to the mirror node for this element.
+        def assign_id(element)
+          SafeAttr.read(element, :id)
+        end
+
+        # Post-process the completed mirror document after all IDs are assigned.
+        # Use this to translate cross-reference targets, etc.
+        # Returns the (possibly modified) document.
+        def finalize!(document)
+          document
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/math_util.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    # MathUtil is the single home for math-content extraction helpers.
+    #
+    # These helpers convert mathML XML objects into strings (stripped of
+    # XML declarations) and extract asciimath from stem elements. They
+    # are used by handlers and renderers that need to carry math content
+    # through the mirror pipeline.
+    module MathUtil
+      STRIP_XML_DECL_PATTERN = /\A<\?xml[^?]*\?>\s?/
+      private_constant :STRIP_XML_DECL_PATTERN
+
+      def self.strip_xml_decl(math_xml)
+        math_xml.sub(STRIP_XML_DECL_PATTERN, "")
+      end
+
+      def self.mathml_from_math(math)
+        xml = math.is_a?(Array) ? math.map(&:to_xml).join : math.to_xml
+        strip_xml_decl(xml)
+      end
+
+      # Extract asciimath text from a stem element. Returns nil if no
+      # asciimath is present.
+      def self.asciimath_from_stem(stem)
+        asciimath = SafeAttr.read(stem, :asciimath)
+        return nil unless asciimath.is_a?(Array)
+
+        parts = asciimath.filter_map do |a|
+          next a if a.is_a?(String)
+          next SafeAttr.read(a, :text).to_s if a.is_a?(Lutaml::Model::Serializable)
+
+          nil
+        end
+        joined = parts.join.strip
+        joined.empty? ? nil : joined
+      end
+
+      # Best-effort plain-text extraction from a stem element. Tries
+      # asciimath first; falls back to SafeAttr :text.
+      def self.text_from_stem(stem)
+        asciimath = asciimath_from_stem(stem)
+        return asciimath if asciimath
+
+        text = SafeAttr.read(stem, :text)
+        return text.to_s if text.is_a?(String) && !text.strip.empty?
+
+        ""
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/metadata.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    # Extracts metadata (title, etc.) from a parsed Metanorma document's
+    # bibdata. This is a standalone service that the pipeline and other
+    # consumers can use without depending on the Handlers layer.
+    module Metadata
+      # Returns the first title string from a bibdata object, or nil.
+      # The bibdata must respond to `title` and return a String, an Array
+      # of Strings, or an Array of Lutaml::Model::Serializables with
+      # `content`.
+      def self.title_from_bibdata(bibdata)
+        return nil unless bibdata
+
+        title = bibdata.title
+        return nil unless title
+
+        case title
+        when String then title
+        when Array
+          first = title.first
+          return nil unless first
+
+          if first.is_a?(String)
+            first
+          elsif first.is_a?(Lutaml::Model::Serializable)
+            Array(first.content).join
+          else
+            first.to_s
+          end
+        else title.to_s
+        end
+      end
+    end
+  end
+end