metanorma-mirror 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5461b164add6bdfedaeef8996c381ce470a4be96d23d289282ede46e46be49f2
+  data.tar.gz: 70fa254f365a47204598f6905e19d9a304690c911eb914767cfbbb3e163a4b2e
+SHA512:
+  metadata.gz: 259835bf04a8dca813ad3f9d15fedd088a9493fc0897ffde4ccb66e33ee9bae4c76b2d3fd84cf4e945ffc7aa4d59b8b5f2d65c35ee4704447ce74864fe75eba1
+  data.tar.gz: 42b0b8fe0f6678a2f3258cba62ccd8e65e8098a5911390612a1a11fda8a10a6db3207d3fd18335b2191d03e555a7b472840a83eb8e483b1574111418127182f8

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,41 @@
+= metanorma-mirror
+
+The Mirror format: a lossless JSON projection of a Metanorma document
+as a typed node tree — blocks, inline runs, marks — preserving document
+order, attributes, and provenance. It is the wire contract consumed by
+the SMART document reader and the HTML JS renderer, and it provides the
+`mirror` provenance object embedded in MKO bundles.
+
+== What lives here
+
+* Node models (`Metanorma::Mirror::Model`) — lutaml-model Serializables
+  with key_value mappings; the JSON wire is the contract.
+* The transformer walk, handler registry, and rewriter.
+* Serializers (JSON, YAML) and the output pipeline.
+
+== What does NOT live here
+
+Model knowledge. Which document classes map to which handlers, mark
+types, rich-HTML renderers, and id categories is *registered* by the
+model gems: metanorma-document and metanorma-standoc seed the defaults
+through the registration seams (`Mirror.register_default`,
+`Mirror.mark_builders`, `Mirror.rich_html_renderers`,
+`Mirror.simple_inline_elements`, `Mirror.inline_text_substitutions`,
+`Mirror.semx_elements`, `Mirror.inline_content_iterator`,
+`Mirror::IdStrategy::Positional.register_category`). A new flavor or
+model registers; this gem never changes (OCP).
+
+== Usage
+
+[source,ruby]
+----
+require "metanorma/mirror"
+require "metanorma/document"   # seeds the default registrations
+
+tree = Metanorma::Mirror::Transformer.new.call(model)
+json = Metanorma::Mirror::Serialization::JsonSerializer.serialize(tree)
+----
+
+== License
+
+BSD-2-Clause.

data/lib/metanorma/mirror/class_table.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    # A class-keyed lookup with ancestor fallback, in registration
+    # order. Consumers register their own model classes to payloads
+    # (lambdas, strings, prefixes); the table — and therefore this gem —
+    # carries no model knowledge. The metanorma-document and
+    # metanorma-standoc seeds register their classes at load time.
+    class ClassTable
+      def initialize
+        @entries = {}
+      end
+
+      def register(klass, payload)
+        @entries[klass] = payload
+        self
+      end
+
+      def lookup(instance)
+        entry_for(instance.class) || ancestor_entry(instance.class)
+      end
+
+      def registered?(klass)
+        @entries.key?(klass)
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      def entry_for(klass)
+        @entries[klass]
+      end
+
+      def ancestor_entry(klass)
+        klass.ancestors.each do |ancestor|
+          next if ancestor == klass
+          break if ancestor == Object
+
+          entry = @entries[ancestor]
+          return entry if entry
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/default_registry.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    # Builds the default handler registry from the registration hooks.
+    # Model gems (metanorma-document, metanorma-standoc, flavors) add
+    # their class-to-handler entries via Mirror.register_default blocks,
+    # run in registration order. The format layer carries no model
+    # knowledge (OCP: new model classes register, this file never
+    # changes).
+    module DefaultRegistry
+      class << self
+        def build
+          registry = HandlerRegistry.new
+          Mirror.default_hooks.each do |hook|
+            hook.call(registry)
+          end
+          registry
+        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/imagemap.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Handlers
+      # Image map: a wrapped figure plus hyperlinked areas (shape,
+      # link, geometry). Duck-typed over SafeAttr reads.
+      module Imagemap
+        def self.call(element, context:)
+          attrs = {
+            id: SafeAttr.read(element, :id),
+            semx_id: SafeAttr.read(element, :semx_id),
+            areas: area_list(element),
+          }.compact
+          content = Svgmap.figure_content(element, context)
+          Handlers.build_node("imagemap", attrs: attrs, content: content)
+        end
+
+        def self.area_list(element)
+          areas = Array(SafeAttr.read(element, :area)).map { |a| area_attrs(a) }
+          areas.empty? ? nil : areas
+        end
+
+        def self.area_attrs(area)
+          ref = Svgmap.reference_of(area)
+          radius = SafeAttr.read(area, :radius)
+          {
+            type: SafeAttr.read(area, :area_type) || SafeAttr.read(area, :type),
+            target: ref,
+            coords: Array(SafeAttr.read(area, :coords)).map do |c|
+              [SafeAttr.read(c, :x), SafeAttr.read(c, :y)]
+            end,
+            radius: radius && radius_attrs(radius),
+          }.compact
+        end
+
+        def self.radius_attrs(radius)
+          [SafeAttr.read(radius, :x), SafeAttr.read(radius, :y)]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# 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. It is consumed by
+        # RichHtmlRenderer, which renders Metanorma XML elements to HTML
+        # directly (the fallback / attribute-value path) during the
+        # forward transform into the mirror IR.
+        #
+        # Marks whose attrs vary per instance (link, xref, eref, span)
+        # carry data in mark.attrs and are not in this table; each
+        # consumer 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
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# 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) take their tag-and-attrs mapping from the shared
+        # Inline::Catalog table.
+        module RichHtmlRenderer
+          # Complex element handlers — these have per-instance attrs or
+          # multi-step rendering and bypass the shared Catalog.
+
+          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 = Mirror.rich_html_renderers.lookup(element)
+            return complex.call(element) if complex
+
+            mark_type = Mirror.simple_inline_elements.lookup(element)
+            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