vectory 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29078da81dfd3def401e196f9c13654a5b2ccc4eefed851c261796cca0e8e9d2
-  data.tar.gz: 602ba638f3ff426687d778c87d4f93bde391cd7aaaa565902374bede727e0bd5
+  metadata.gz: 1825d8ed689d1eb94da1c473ffd9671bc3237471f3f4b675d6f2d8ff6db4e2a7
+  data.tar.gz: 7d9ee417ac1b74b481589a83f45a359d556f1c3d2aa401149f57439c39085811
 SHA512:
-  metadata.gz: 32c32817c07c2578914427b923f82f97cbfd71249d11d10c07dcab6ad051d647679bd7cffdcaf6b104a6bd928dc8fe71bba32e686ebb00d1fa2c2b3758b93cd0
-  data.tar.gz: 3636e536af14c71d4efd99136c0408528412a20b7e50e12efd33147d8c7e5bea1bb70128c35af71b9b439febd2ab3636c29a58984e04b49ecb146c292891180e
+  metadata.gz: 03d2373df0d22c8168dddecb4e073a62974db0d00b898d3a9896d839390c9aba6c959553d2e172e84534ece21913d0aa503d6469f600fae15e7bf5f32cc7a5b7
+  data.tar.gz: 169c5f762f9eb0a9897e7277633a1e7181f17e918341198b8d420ec482a3c83425d1ad45de4bce6428970d1850bc916fd91231a6c22dbf01c7ef6660070a7e5b

data/README.adoc

@@ -169,15 +169,49 @@ Vectory::Eps.from_path("img.eps").to_uri.content
 ==== SVG mapping (for the metanorma project)
 
 Vectory can integrate SVG files into XML or HTML, respecting internal id and
-link references:
+link references. It supports ID disambiguation for multi-document and multi-svgmap
+scenarios.
+
+===== Basic usage
 
 [source,ruby]
 ----
 xml_string = Vectory::SvgMapping.from_path("doc.xml").to_xml
 ----
 
-In order to do that an initial XML should support the `svgmap` tag with links
-mapping. For example, it can convert XML like this:
+===== ID suffixing for uniqueness
+
+When processing multiple documents or multiple svgmaps within a document,
+SVG IDs must be unique to avoid conflicts. Vectory applies two types of suffixes:
+
+*ID suffix* (Cross-document uniqueness)::
+An optional suffix derived from document or container identity (e.g., `_ISO_17301-1_2016`).
+This provides uniqueness across documents or collections.
+
+*Index suffix* (Multi-svgmap uniqueness)::
+Automatically applied based on the svgmap's position in the document (0, 1, 2, ...).
+Formatted as a 9-digit zero-padded number (e.g., `_000000000`, `_000000001`).
+This provides uniqueness when a document contains multiple svgmaps.
+
+.Final ID composition
+[source]
+----
+Original ID:  fig1
+With ID suffix only:  fig1_ISO_17301-1_2016
+With both suffixes:   fig1_ISO_17301-1_2016_000000000
+----
+
+===== Usage with ID suffix
+
+[source,ruby]
+----
+mapping = Vectory::SvgMapping.new(doc, "", id_suffix: "_ISO_17301-1_2016")
+xml_string = mapping.call.to_xml
+----
+
+===== Input format
+
+The input XML must support the `svgmap` tag with link mapping.
 
 [source,xml]
 ----
@@ -187,8 +221,8 @@ mapping. For example, it can convert XML like this:
     <xref target="ref1">Computer</xref>
   </target>
   <target href="http://www.example.com">
-    <link target="http://www.example.com">Phone</link><
-  /target>
+    <link target="http://www.example.com">Phone</link>
+  </target>
 </svgmap>
 ----
 
@@ -196,16 +230,12 @@ mapping. For example, it can convert XML like this:
 [source,xml]
 ----
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Generator: Adobe Illustrator 25.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
-<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
-	 viewBox="0 0 595.28 841.89" style="enable-background:new 0 0 595.28 841.89;" xml:space="preserve">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
   <style type="text/css">
-          #Layer_1 { fill:none }
-          svg[id = 'Layer_1'] { fill:none }
+    #Layer_1 { fill:none }
+    svg[id = 'Layer_1'] { fill:none }
     .st0{fill:none;stroke:#000000;stroke-miterlimit:10;}
   </style>
-  <image style="overflow:visible;" width="368" height="315" xlink:href="data:image/gif;base64,R0lG..ommited to save space" transform="matrix(1 0 0 1 114 263.8898)">
-  </image>
   <a xlink:href="mn://action_schema" xlink:dummy="Layer_1">
     <rect x="123.28" y="273.93" class="st0" width="88.05" height="41.84"/>
   </a>
@@ -218,15 +248,14 @@ mapping. For example, it can convert XML like this:
 </svg>
 ----
 
-into XML containing inline SVG tags. Notice changes in the `id` attributes and
-the `a` tags:
+===== Output format
 
 [source,xml]
 ----
 <figure>
-  <svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' version='1.1' id='Layer_1_000000001' x='0px' y='0px' viewBox='0 0 595.28 841.89' style='enable-background:new 0 0 595.28 841.89;' xml:space='preserve'>
-    <style> ..ommited to save space </style>
-    <image> ..ommited </image>
+  <svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' version='1.1'
+       id='Layer_1_000000001' x='0px' y='0px' viewBox='0 0 595.28 841.89'>
+    <style> #Layer_1_000000001 { fill:none }</style>
     <a xlink:href='#ref1' xlink:dummy='Layer_1_000000001'>
       <rect x='123.28' y='273.93' class='st0' width='88.05' height='41.84'/>
     </a>
@@ -240,53 +269,39 @@ the `a` tags:
 </figure>
 ----
 
-It also supports SVG in a form of an inline tag:
+===== Inline SVG support
+
+SVG can also be provided inline within the svgmap:
 
 [source,xml]
 ----
 <svgmap id="_60dadf08-48d4-4164-845c-b4e293e00abd">
   <figure>
-    <svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' version='1.1' id='Layer_1' x='0px' y='0px' viewBox='0 0 595.28 841.89' style='enable-background:new 0 0 595.28 841.89;' xml:space='preserve'>
-      <a href="mn://action_schema" >
-        <rect x="123.28" y="273.93" class="st0" width="88.05" height="41.84"/>
-      </a>
-      <a href="mn://basic_attribute_schema" >
-        <rect x="324.69" y="450.52" class="st0" width="132.62" height="40.75"/>
-      </a>
-      <a xlink:href="mn://support_resource_schema" >
-        <rect x="324.69" y="528.36" class="st0" width="148.16" height="40.75"/>
+    <svg xmlns='http://www.w3.org/2000/svg' id='Layer_1'>
+      <a href="mn://action_schema">
+        <rect x="123.28" y="273.93" class="st0"/>
       </a>
     </svg>
   </figure>
   <target href="mn://action_schema">
     <xref target="ref1">Computer</xref>
   </target>
-  <target href="http://www.example.com">
-    <link target="http://www.example.com">Phone</link>
-  </target>
 </svgmap>
 ----
 
-and datauri:
+===== Data URI support
+
+Images can be provided as data URIs:
 
 [source,xml]
 ----
 <svgmap id="_60dadf08-48d4-4164-845c-b4e293e00abd">
   <figure>
-    <image src='data:image/svg+xml;base64,PD94..ommited to save space' id='__ISO_17301-1_2016' mimetype='image/svg+xml' height='auto' width='auto' alt='Workmap1'/>
+    <image src='data:image/svg+xml;base64,PD94...'/>
   </figure>
   <target href="href1.htm">
     <xref target="ref1">Computer</xref>
   </target>
-  <target href="mn://basic_attribute_schema">
-    <link target="http://www.example.com">Phone</link>
-  </target>
-  <target href="mn://support_resource_schema">
-    <eref type="express" bibitemid="express_action_schema" citeas="">
-      <localityStack><locality type="anchor"><referenceFrom>action_schema.basic</referenceFrom></locality></localityStack>
-      Coffee
-    </eref>
-  </target>
 </svgmap>
 ----
 
@@ -355,7 +370,7 @@ Vector#width
 
 == Development
 
-=== Regenerating Test Fixtures
+=== Regenerating test fixtures
 
 Some test fixtures are generated by external tools (Ghostscript, Inkscape, cairo).
 When these tools are updated, the reference files may need to be regenerated.

data/docs/reference/api.adoc

@@ -339,7 +339,7 @@ rescue Vectory::ConversionError => e
 end
 ----
 
-=== Dimension Query
+=== Dimension query
 
 [source,ruby]
 ----
@@ -348,7 +348,89 @@ width, height = eps.dimensions
 puts "Dimensions: #{width}x#{height}"
 ----
 
-## See Also
+== SVG mapping
+
+Integrates SVG content into XML documents with ID disambiguation for multi-document scenarios.
+
+=== Vectory::SvgMapping
+
+Processes XML documents containing `<svgmap>` elements, extracting and integrating SVG content.
+
+[source,ruby]
+----
+# Basic usage
+xml_string = Vectory::SvgMapping.from_path("doc.xml").to_xml
+
+# With ID suffix for cross-document uniqueness
+mapping = Vectory::SvgMapping.new(doc, "", id_suffix: "_ISO_17301-1_2016")
+xml_string = mapping.call.to_xml
+----
+
+**Factory methods**:
+
+* `Vectory::SvgMapping.from_path(path)` - Load from file path
+* `Vectory::SvgMapping.from_xml(xml)` - Load from XML string
+* `Vectory::SvgMapping.new(doc, local_directory, id_suffix: nil)` - Direct instantiation
+
+**Parameters**:
+
+* `doc` - Nokogiri XML Document containing svgmap elements
+* `local_directory` - Directory for resolving relative file paths
+* `id_suffix` - Optional suffix for cross-document ID uniqueness (e.g., "_ISO_17301-1_2016")
+
+**Methods**:
+
+* `#call` - Process all svgmap elements, returns processed document
+* `#to_xml` - Process and return XML string
+
+=== Vectory::SvgDocument
+
+Represents an SVG document and handles ID suffixing for uniqueness.
+
+[source,ruby]
+----
+# Create from SVG content
+svg_doc = Vectory::SvgDocument.new(svg_content)
+
+# Apply both ID suffix and index suffix
+svg_doc.namespace(index, links, xpath_to_remove, id_suffix: "_ISO_17301-1_2016")
+result = svg_doc.content
+----
+
+**Constructor**:
+
+* `Vectory::SvgDocument.new(content)` - Create from SVG XML string
+
+**Methods**:
+
+* `namespace(index_suffix, links, xpath_to_remove, id_suffix: nil)` - Apply transformations
+** `index_suffix` - Position-based suffix (0, 1, 2...) formatted as 9-digit zero-padded
+** `links` - Hash mapping hrefs to targets
+** `xpath_to_remove` - XPath for elements to remove (processing instructions)
+** `id_suffix` - Optional identity-based suffix for cross-document uniqueness
+
+* `content` - Returns processed SVG as XML string
+* `remap_links(map)` - Remap internal links
+* `apply_id_suffix(id_suffix)` - Apply ID suffix
+* `apply_index_suffix(index)` - Apply index suffix
+
+=== ID Suffixing
+
+SVG IDs are suffixed in two stages:
+
+[source]
+----
+# Stage 1: ID suffix (cross-document uniqueness)
+fig1 → fig1_ISO_17301-1_2016
+
+# Stage 2: Index suffix (multi-svgmap uniqueness)
+fig1_ISO_17301-1_2016 → fig1_ISO_17301-1_2016_000000000
+----
+
+* **ID suffix** (`id_suffix` parameter): Derived from document/container identity. Optional.
+* **Index suffix** (`index_suffix` parameter): Zero-padded position (0, 1, 2... → _000000000, _000000001). Automatically applied.
+
+== See Also
 
 * link:../guides/error-handling/[Error Handling Guide] - Common errors and solutions
 * link:../understanding/architecture/[Architecture] - Design patterns

data/lib/vectory/svg_document.rb

@@ -1,11 +1,30 @@
 require "nokogiri"
 
 module Vectory
+  # Represents and processes an SVG document within XML.
+  #
+  # SvgDocument handles SVG ID suffixing for uniqueness in multi-document
+  # and multi-svgmap scenarios. It applies two types of suffixes:
+  #
+  # 1. **ID suffix** - Derived from document/container identity
+  #    Provides cross-document uniqueness
+  #
+  # 2. **Index suffix** - Derived from svgmap position
+  #    Provides multi-svgmap uniqueness within a document
+  #
+  # Final ID format: <original_id><id_suffix><index_suffix>
+  # Example: fig1 + _ISO_17301-1_2016 + _000000000 = fig1_ISO_17301-1_2016_000000000
+  #
   class SvgDocument
     SVG_NS = "http://www.w3.org/2000/svg".freeze
 
     class << self
-      # Update instances of id in style statements in a nokogiri document
+      # Updates ID references in CSS style statements within a document.
+      #
+      # @param document [Nokogiri::XML::Document] The SVG document
+      # @param ids [Array<String>] IDs to update
+      # @param suffix [Integer, String] The suffix to apply (integers are zero-padded)
+      # @return [void]
       def update_ids_css(document, ids, suffix)
         suffix = suffix.is_a?(Integer) ? sprintf("%09d", suffix) : suffix
         document.xpath(".//m:style", "m" => SVG_NS).each do |s|
@@ -17,7 +36,12 @@ module Vectory
         end
       end
 
-      # Update instances of id in style statements in the string style
+      # Updates ID references in a CSS style string.
+      #
+      # @param style [String] The CSS style content
+      # @param ids [Array<String>] IDs to update
+      # @param suffix [Integer, String] The suffix to apply (integers are zero-padded)
+      # @return [String] Updated style content
       def update_ids_css_string(style, ids, suffix)
         ids.each do |i|
           style = style.gsub(%r[##{i}\b],
@@ -30,6 +54,12 @@ module Vectory
         style
       end
 
+      # Updates ID attributes in SVG elements.
+      #
+      # @param document [Nokogiri::XML::Document] The SVG document
+      # @param ids [Array<String>] IDs to update
+      # @param suffix [Integer, String] The suffix to apply (integers are zero-padded)
+      # @return [void]
       def update_ids_attrs(document, ids, suffix)
         suffix = suffix.is_a?(Integer) ? sprintf("%09d", suffix) : suffix
         document.xpath(". | .//*[@*]").each do |a|
@@ -42,20 +72,57 @@ module Vectory
       end
     end
 
+    # Creates a new SvgDocument from SVG content.
+    #
+    # @param content [String] SVG XML content
     def initialize(content)
       @document = Nokogiri::XML(content)
     end
 
+    # Returns the processed SVG content as XML string.
+    #
+    # @return [String] SVG XML content
     def content
       @document.root.to_xml
     end
 
-    def namespace(suffix, links, xpath_to_remove)
+    # Applies namespace transformations to the SVG document.
+    #
+    # This method performs the following operations in order:
+    # 1. Remap internal links to their targets
+    # 2. Apply ID suffix (if provided) for cross-document uniqueness
+    # 3. Apply index suffix for multi-svgmap uniqueness
+    # 4. Remove processing instructions
+    #
+    # @param index_suffix [Integer] The position-based suffix (0, 1, 2...)
+    #   Converted to 9-digit zero-padded string (e.g., "_000000000")
+    # @param links [Hash{String => String}] Mapping of link hrefs to their targets
+    # @param xpath_to_remove [String] XPath for elements to remove (processing instructions)
+    # @param id_suffix [String, nil] Optional suffix derived from document/container
+    #   identity. Applied BEFORE index_suffix for two-stage disambiguation.
+    #   Example: "_ISO_17301-1_2016"
+    #
+    # @return [self] The processed document
+    def namespace(index_suffix, links, xpath_to_remove, id_suffix: nil)
       remap_links(links)
-      suffix_ids(suffix)
+
+      # Apply ID suffix first (cross-document uniqueness)
+      # Then apply index suffix (multi-svgmap uniqueness)
+      # Final format: <original_id><id_suffix><index_suffix>
+      if id_suffix
+        apply_id_suffix(id_suffix)
+      end
+
+      apply_index_suffix(index_suffix)
       remove_xpath(xpath_to_remove)
+
+      self
     end
 
+    # Remaps internal SVG links to their target definitions.
+    #
+    # @param map [Hash{String => String}] Mapping of expanded hrefs to targets
+    # @return [self] The document
     def remap_links(map)
       @document.xpath(".//m:a", "m" => SVG_NS).each do |a|
         href_attrs = ["xlink:href", "href"]
@@ -67,16 +134,54 @@ module Vectory
       self
     end
 
-    def suffix_ids(suffix)
+    # Applies an ID suffix to all SVG IDs for cross-document uniqueness.
+    #
+    # This is called BEFORE index-based suffixing.
+    #
+    # @param id_suffix [String] The suffix to apply (e.g., "_ISO_17301-1_2016")
+    # @return [self] The document
+    def apply_id_suffix(id_suffix)
+      ids = collect_ids
+      return if ids.empty?
+
+      self.class.update_ids_attrs(@document.root, ids, id_suffix)
+      self.class.update_ids_css(@document.root, ids, id_suffix)
+
+      self
+    end
+
+    # Applies an index-based suffix to all SVG IDs.
+    #
+    # The index is converted to a 9-digit zero-padded string.
+    # This is called AFTER ID-based suffixing.
+    #
+    # @param index [Integer] The index suffix (converted to "_000000000" format)
+    # @return [self] The document
+    def apply_index_suffix(index)
       ids = collect_ids
       return if ids.empty?
 
-      self.class.update_ids_attrs(@document.root, ids, suffix)
-      self.class.update_ids_css(@document.root, ids, suffix)
+      self.class.update_ids_attrs(@document.root, ids, index)
+      self.class.update_ids_css(@document.root, ids, index)
 
       self
     end
 
+    # Applies an index-based suffix to all SVG IDs.
+    #
+    # @deprecated Use {#apply_index_suffix} instead for clarity.
+    # Maintained for backward compatibility.
+    #
+    # @param suffix [Integer, String] The suffix to apply (integers are zero-padded)
+    # @return [self] The document
+    def suffix_ids(suffix)
+      apply_index_suffix(suffix)
+    end
+
+    # Removes elements matching the given XPath.
+    #
+    # @param xpath [String] XPath expression for elements to remove
+    # @return [self] The document
     def remove_xpath(xpath)
       @document.xpath(xpath).remove
 
@@ -85,6 +190,9 @@ module Vectory
 
     private
 
+    # Collects all id attribute values from the SVG document.
+    #
+    # @return [Array<String>] All ID values
     def collect_ids
       @document.xpath("./@id | .//@id").map(&:value)
     end

data/lib/vectory/svg_mapping.rb

@@ -2,12 +2,45 @@ require_relative "svg"
 require_relative "svg_document"
 
 module Vectory
+  # Processes SVG mapping in XML documents.
+  #
+  # SvgMapping integrates SVG content into XML documents by:
+  # - Extracting SVG from image tags or inline <svg> elements
+  # - Processing <target> elements to build link mappings
+  # - Applying ID suffixes for uniqueness in multi-document scenarios
+  # - Simplifying svgmap structure for final output
+  #
+  # == ID Suffixing
+  #
+  # SVG IDs are suffixed in two stages to ensure uniqueness:
+  #
+  # 1. **ID suffix** (optional) - Derived from document/container identity
+  #    Provides cross-document uniqueness (e.g., <id>_ISO_17301-1_2016)
+  #
+  # 2. **Index suffix** - Derived from svgmap position in document
+  #    Provides multi-svgmap uniqueness (e.g., <id>_000000000)
+  #
+  # Final ID: <original_id><id_suffix><index_suffix>
+  # Example: fig1_ISO_17301-1_2016_000000000
+  #
+  # @example Basic usage
+  #   xml_string = Vectory::SvgMapping.from_path("doc.xml").to_xml
+  #
+  # @example With ID suffix for multi-document uniqueness
+  #   mapping = Vectory::SvgMapping.new(doc, "", id_suffix: "_ISO_17301-1_2016")
+  #   xml_string = mapping.call.to_xml
+  #
   class SvgMapping
+    # Namespace helper for XML namespace handling
     class Namespace
+      # @param xmldoc [Nokogiri::XML::Document] The XML document
       def initialize(xmldoc)
         @namespace = xmldoc.root.namespace
       end
 
+      # Converts XPath to use document namespace
+      # @param path [String] The XPath expression
+      # @return [String] XPath with namespace prefixes
       def ns(path)
         return path if @namespace.nil?
 
@@ -19,22 +52,45 @@ module Vectory
     end
 
     SVG_NS = "http://www.w3.org/2000/svg".freeze
+    private_constant :SVG_NS
+
+    # XPath to remove processing instructions during SVG processing
     PROCESSING_XPATH =
       "processing-instruction()|.//processing-instruction()".freeze
+    private_constant :PROCESSING_XPATH
 
+    # Creates an SvgMapping from an XML file path.
+    #
+    # @param path [String] Path to the XML file
+    # @return [Vectory::SvgMapping] New mapping instance
     def self.from_path(path)
       new(Nokogiri::XML(File.read(path)))
     end
 
+    # Creates an SvgMapping from an XML string.
+    #
+    # @param xml [String] XML content
+    # @return [Vectory::SvgMapping] New mapping instance
     def self.from_xml(xml)
       new(Nokogiri::XML(xml))
     end
 
-    def initialize(doc, local_directory = "")
+    # Initializes a new SvgMapping processor.
+    #
+    # @param doc [Nokogiri::XML::Document] The document containing svgmap elements
+    # @param local_directory [String] Directory for resolving relative file paths
+    # @param id_suffix [String, nil] Optional suffix derived from document/container
+    #   identity. Applied before the index suffix to provide cross-document
+    #   uniqueness. Example: "_ISO_17301-1_2016"
+    def initialize(doc, local_directory = "", id_suffix: nil)
       @doc = doc
       @local_directory = local_directory
+      @id_suffix = id_suffix
     end
 
+    # Processes all svgmap elements in the document.
+    #
+    # @return [Nokogiri::XML::Document] The processed document
     def call
       @namespace = Namespace.new(@doc)
 
@@ -45,17 +101,24 @@ module Vectory
       @doc
     end
 
+    # Processes and returns XML string.
+    #
+    # @return [String] XML representation of processed document
     def to_xml
       call.to_xml
     end
 
     private
 
-    def process_svgmap(svgmap, suffix)
+    # Processes a single svgmap element.
+    #
+    # @param svgmap [Nokogiri::XML::Element] The svgmap element to process
+    # @param index [Integer] Position of this svgmap in the document (0-indexed)
+    def process_svgmap(svgmap, index)
       image = extract_image_tag(svgmap)
       return unless image
 
-      content = generate_content(image, svgmap, suffix)
+      content = generate_content(image, svgmap, index)
       return unless content
 
       image.replace(content)
@@ -63,6 +126,10 @@ module Vectory
       simplify_svgmap(svgmap)
     end
 
+    # Extracts the image element (SVG inline or image with src) from svgmap.
+    #
+    # @param svgmap [Nokogiri::XML::Element] The svgmap element
+    # @return [Nokogiri::XML::Element, nil] The image/svg element or nil
     def extract_image_tag(svgmap)
       image = svgmap.at(@namespace.ns(".//image"))
       return image if image && image["src"] && !image["src"].empty?
@@ -70,16 +137,27 @@ module Vectory
       svgmap.at(".//m:svg", "m" => SVG_NS)
     end
 
-    def generate_content(image, svgmap, suffix)
+    # Generates processed SVG content for an svgmap.
+    #
+    # @param image [Nokogiri::XML::Element] The image/svg element
+    # @param svgmap [Nokogiri::XML::Element] The parent svgmap element
+    # @param index [Integer] Index suffix to apply
+    # @return [String, nil] Processed SVG content or nil if invalid
+    def generate_content(image, svgmap, index)
       document = build_svg_document(image)
       return unless document
 
       links_map = from_targets_to_links_map(svgmap)
-      document.namespace(suffix, links_map, PROCESSING_XPATH)
+      # Pass nil for id_suffix here; it's already handled in SvgDocument.namespace
+      document.namespace(index, links_map, PROCESSING_XPATH, id_suffix: @id_suffix)
 
       document.content
     end
 
+    # Builds an SvgDocument from an image element.
+    #
+    # @param image [Nokogiri::XML::Element] The image element
+    # @return [Vectory::SvgDocument, nil] The SVG document or nil if invalid
     def build_svg_document(image)
       vector = build_vector(image)
       return unless vector
@@ -87,6 +165,10 @@ module Vectory
       SvgDocument.new(vector.content)
     end
 
+    # Builds a Vector from an image element.
+    #
+    # @param image [Nokogiri::XML::Element] The image element
+    # @return [Vectory::Vector, nil] The vector or nil if invalid
     def build_vector(image)
       return Vectory::Svg.from_content(image.to_xml) if image.name == "svg"
 
@@ -101,6 +183,10 @@ module Vectory
       Vectory::Svg.from_path(path)
     end
 
+    # Builds a mapping from target hrefs to their link targets.
+    #
+    # @param svgmap [Nokogiri::XML::Element] The svgmap element
+    # @return [Hash{String => String}] Mapping of href to target
     def from_targets_to_links_map(svgmap)
       targets = svgmap.xpath(@namespace.ns("./target"))
       targets.each_with_object({}) do |target_tag, m|
@@ -114,6 +200,10 @@ module Vectory
       end
     end
 
+    # Extracts link target from a target element.
+    #
+    # @param target_tag [Nokogiri::XML::Element] The target element
+    # @return [String, nil] The link target or nil
     def link_target(target_tag)
       xref = target_tag.at(@namespace.ns("./xref"))
       return "##{xref['target']}" if xref
@@ -124,6 +214,10 @@ module Vectory
       link["target"]
     end
 
+    # Simplifies svgmap after processing.
+    # Removes svgmap wrapper if no more target elements with eref.
+    #
+    # @param svgmap [Nokogiri::XML::Element] The svgmap element
     def simplify_svgmap(svgmap)
       return if svgmap.at(@namespace.ns("./target/eref"))
 

data/lib/vectory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectory
-  VERSION = "0.8.1"
+  VERSION = "0.8.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vectory
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-28 00:00:00.000000000 Z
+date: 2026-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64