uniword 1.3.0 → 1.4.0

data/lib/uniword/docx/part_loader/xml_model_loader.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads fixed-path XML parts: parses the part's XML with the
+      # definition's loader_model and assigns the model to the
+      # definition's package attribute. Covers every part whose load
+      # is "parse one part into one attribute": the content types,
+      # all rels parts, docProps, the main document, styles,
+      # numbering, settings, font table, web settings, theme,
+      # footnotes, endnotes, and comments.
+      #
+      # Definitions with a path_resolution rule resolve their path
+      # dynamically (main document via the package officeDocument
+      # relationship; its rels part as the sidecar of the resolved
+      # path), falling back to the definition's fixed path.
+      class XmlModelLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] part to load
+        # @return [void]
+        def load(context, definition)
+          content = read_content(context, definition)
+          return unless content
+
+          model = definition.loader_model.from_xml(content)
+          context.package.method(:"#{definition.package_attribute}=")
+            .call(model)
+        end
+
+        private
+
+        # Part content from the first candidate path present in the
+        # ZIP, preserving the historic resolved-then-fixed fallback.
+        def read_content(context, definition)
+          candidate_paths(context, definition).each do |path|
+            content = context.zip_content[path]
+            return content if content
+          end
+          nil
+        end
+
+        def candidate_paths(context, definition)
+          case definition.path_resolution
+          when :office_document
+            [context.main_document_path, definition.path].compact
+          when :office_document_rels
+            [context.main_document_rels_path, definition.path].compact
+          else
+            [definition.path]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/part_loader.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Registry-driven loader for DOCX package parts.
+    #
+    # Replaces the former hand-written per-part sequence in
+    # Package.from_zip_content: parts load by iterating
+    # Ooxml::PartRegistry.loadable (ordered by
+    # Ooxml::PartDefinition#load_priority) and dispatching each
+    # definition to the loader strategy registered under
+    # Ooxml::PartDefinition#loader.
+    #
+    # Open/closed: a new part kind adds a strategy class plus a
+    # register_loader call and a PartRegistry registration — this loop
+    # never changes.
+    #
+    # @example Load parts into a package
+    #   package = Package.new
+    #   PartLoader.load(zip_content, package, zip_path: "doc.docx")
+    class PartLoader
+      autoload :LoadContext, "#{__dir__}/part_loader/load_context"
+      autoload :XmlModelLoader, "#{__dir__}/part_loader/xml_model_loader"
+      autoload :CustomXmlLoader,
+               "#{__dir__}/part_loader/custom_xml_loader"
+      autoload :HeaderFooterLoader,
+               "#{__dir__}/part_loader/header_footer_loader"
+      autoload :ChartLoader, "#{__dir__}/part_loader/chart_loader"
+      autoload :ImageLoader, "#{__dir__}/part_loader/image_loader"
+      autoload :EmbeddingLoader,
+               "#{__dir__}/part_loader/embedding_loader"
+      autoload :ThemeMediaLoader,
+               "#{__dir__}/part_loader/theme_media_loader"
+      autoload :RawPartLoader,
+               "#{__dir__}/part_loader/raw_part_loader"
+
+      class << self
+        # Load every registered part from extracted ZIP content into
+        # the package.
+        #
+        # @param zip_content [Hash] extracted ZIP entries
+        #   (package path => content)
+        # @param package [Package] package to populate
+        # @param zip_path [String, nil] original ZIP path for binary
+        #   re-extraction (image bytes)
+        # @return [Package] the populated package
+        def load(zip_content, package, zip_path: nil)
+          context = LoadContext.new(zip_content: zip_content,
+                                    package: package, zip_path: zip_path)
+          Ooxml::PartRegistry.loadable.each do |definition|
+            loader_for(definition.loader).load(context, definition)
+          end
+          package
+        end
+
+        # Register a loader strategy under a key.
+        #
+        # @param key [Symbol] PartDefinition#loader value
+        # @param strategy [#load] strategy responding to
+        #   +load(context, definition)+
+        # @return [Object] the registered strategy
+        def register_loader(key, strategy)
+          loaders[key.to_sym] = strategy
+        end
+
+        # @param key [Symbol] PartDefinition#loader value
+        # @return [#load] the registered strategy
+        # @raise [ArgumentError] when no strategy is registered
+        def loader_for(key)
+          loaders.fetch(key.to_sym) do
+            raise ArgumentError, "unknown part loader: #{key.inspect}"
+          end
+        end
+
+        private
+
+        def loaders
+          @loaders ||= {}
+        end
+      end
+
+      register_loader(:xml_model, XmlModelLoader.new)
+      register_loader(:custom_xml, CustomXmlLoader.new)
+      register_loader(:header_footer, HeaderFooterLoader.new)
+      register_loader(:chart, ChartLoader.new)
+      register_loader(:image, ImageLoader.new)
+      register_loader(:embedding, EmbeddingLoader.new)
+      register_loader(:theme_media, ThemeMediaLoader.new)
+      register_loader(:raw, RawPartLoader.new)
+    end
+  end
+end

data/lib/uniword/docx/raw_part.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # A package part no Ooxml::PartDefinition models, carried verbatim
+    # for round-trip fidelity (e.g. docProps/meta.xml, glossary
+    # documents, VBA projects, unmodelled .rels sidecars).
+    #
+    # Unlike document-scoped parts (charts, images, embeddings), a raw
+    # part keeps its full package-relative +path+ — raw parts live
+    # anywhere in the package, not only under word/. Content is the
+    # exact source byte stream (binary-safe; never parsed or
+    # re-encoded), plus the content type the source
+    # [Content_Types].xml declared for it (Override first, then
+    # Default by extension; nil when the source declared neither).
+    #
+    # The relationship referencing the part (when one exists in a
+    # modelled .rels part) is recorded as +r_id+/+rel_type+ metadata
+    # for introspection parity with other part kinds; emission never
+    # uses it — relationships re-serialize from the loaded rels
+    # models, so the source rel survives untouched.
+    #
+    # Raw parts are a fallback: PartLoader claims every registry-known
+    # path first and RawPartLoader carries only the remainder, so a
+    # part is never emitted twice.
+    #
+    # @example
+    #   part = RawPart.new(
+    #     path: "docProps/meta.xml",
+    #     content: bytes,
+    #     content_type: "application/xml",
+    #   )
+    #   part.package_paths # => ["docProps/meta.xml"]
+    class RawPart < Part
+      # @return [String, nil] package-relative path, verbatim
+      attr_writer :path
+
+      # @param path [String, nil] package-relative path
+      #   (e.g. "docProps/meta.xml")
+      # @param content [String, nil] raw part bytes (binary-safe)
+      # @param content_type [String, nil] content type declared by the
+      #   source [Content_Types].xml
+      # @param r_id [String, nil] id of the relationship referencing
+      #   this part (metadata only)
+      # @param rel_type [String, nil] type of the relationship
+      #   referencing this part (metadata only)
+      def initialize(path: nil, content: nil, content_type: nil,
+                     r_id: nil, rel_type: nil)
+        super(content: content, content_type: content_type,
+              r_id: r_id, rel_type: rel_type)
+        @path = path
+      end
+
+      # Wrap a raw-hash entry ({ path:, content:, content_type: })
+      # into a RawPart. Used by PartCollection to normalize hash
+      # assignments.
+      #
+      # @param hash [Hash] raw hash entry
+      # @return [RawPart]
+      def self.from_hash(hash)
+        new(path: hash[:path], content: hash[:content],
+            content_type: hash[:content_type],
+            r_id: hash[:r_id], rel_type: hash[:rel_type])
+      end
+
+      # Package-relative path of the emitted part, carried verbatim
+      # (overrides Part's word/-prefixed target derivation).
+      #
+      # @return [String, nil] e.g. "word/glossary/document.xml"
+      def path
+        @path
+      end
+    end
+  end
+end

data/lib/uniword/docx/reconciler/helpers.rb

@@ -98,45 +98,24 @@ module Uniword
           end
         end
 
-        # -- Element order --
+        # -- Element order (delegates to Ooxml::ElementOrder) --
 
+        # Idempotent singleton insert in schema position.
         def ensure_element_in_order(model, tag_name, after: nil, before: nil)
-          order = model.element_order
-          return unless order
-
-          return if order.any? { |e| e.name == tag_name }
-
-          entry = Lutaml::Xml::Element.new("Element", tag_name)
-
-          if after
-            idx = order.index { |e| e.name == after }
-            thaw_and_insert(model, order, idx ? idx + 1 : order.size, entry)
-          elsif before
-            idx = order.index { |e| e.name == before }
-            thaw_and_insert(model, order, idx || 0, entry)
-          else
-            thaw_and_append(model, order, entry)
-          end
+          Ooxml::ElementOrder.insert_once(model, tag_name,
+                                          after: after, before: before)
         end
 
+        # Positional insert for repeatable elements.
         def insert_element_order(obj, name, position)
           order = obj.element_order
           return unless order
-
           return if order.any? { |e| e.name == name }
 
-          entry = Lutaml::Xml::Element.new("Element", name, node_type: :element)
-          thaw_and_insert(obj, order, position, entry)
-        end
-
-        # lutaml-model freezes element_order after XML parsing.
-        # Replace the frozen array with a mutable copy when modification is needed.
-        def thaw_and_insert(model, order, position, entry)
-          model.element_order = order.dup.insert(position, entry)
-        end
-
-        def thaw_and_append(model, order, entry)
-          model.element_order = order.dup << entry
+          Ooxml::ElementOrder.insert_at(
+            obj, position, Lutaml::Xml::Element.new("Element", name,
+                                                    node_type: :element)
+          )
         end
 
         # -- Run utilities (delegate to RunUtils) --

data/lib/uniword/docx/reconciler/package_structure.rb

@@ -110,8 +110,7 @@ module Uniword
             [Ooxml::PartRegistry.find_by_key(:comments), package.comments],
           ]
 
-          sources = package.bibliography_sources ||
-            package.document&.bibliography_sources
+          sources = package.document&.bibliography_sources
           if sources
             defs << [Ooxml::PartRegistry.find_by_key(:bibliography), sources]
           end
@@ -172,10 +171,10 @@ module Uniword
           end
 
           chart = Ooxml::PartRegistry.find_by_key(:chart)
-          (package.document&.chart_parts&.values || []).each do |data|
-            next unless data[:target]
+          (package.document&.chart_parts&.values || []).each do |part|
+            next unless part.target
 
-            alloc.alloc_rid(target: data[:target], type: chart.rel_type)
+            alloc.alloc_rid(target: part.target, type: chart.rel_type)
           end
         end
 

data/lib/uniword/docx/reconciler/referential_integrity.rb

@@ -483,86 +483,11 @@ module Uniword
           segments.join("/")
         end
 
-        # Package paths the save path emits, derived from the model —
-        # mirrors serialize_package_parts / inject_* emission.
+        # Package paths the save path emits — answered by the
+        # PartRegistry (single authority), derived from model presence
+        # and part collections.
         def carried_part_paths
-          paths = carried_word_parts + carried_docprops_parts
-          paths.concat(custom_xml_item_paths)
-          paths.concat(document_part_paths)
-          paths.to_set
-        end
-
-        # [model, package path] pairs for single-instance word/ parts.
-        def carried_word_parts
-          pairs = core_word_pairs + note_word_pairs
-          pairs.filter_map { |model, path| path if model }
-        end
-
-        def core_word_pairs
-          [
-            [package.document, "word/document.xml"],
-            [package.styles, "word/styles.xml"],
-            [package.numbering, "word/numbering.xml"],
-            [package.settings, "word/settings.xml"],
-            [package.font_table, "word/fontTable.xml"],
-            [package.web_settings, "word/webSettings.xml"],
-          ]
-        end
-
-        def note_word_pairs
-          [
-            [package.theme, "word/theme/theme1.xml"],
-            [package.footnotes, "word/footnotes.xml"],
-            [package.endnotes, "word/endnotes.xml"],
-            [package.comments, "word/comments.xml"],
-            [package.document&.bibliography_sources, "word/sources.xml"],
-          ]
-        end
-
-        # [model, package path] pairs for single-instance docProps/ parts.
-        def carried_docprops_parts
-          pairs = [
-            [package.core_properties, "docProps/core.xml"],
-            [package.app_properties, "docProps/app.xml"],
-            [package.custom_properties, "docProps/custom.xml"],
-          ]
-          pairs.filter_map { |model, path| path if model }
-        end
-
-        def custom_xml_item_paths
-          (package.custom_xml_items || []).flat_map do |item|
-            paths = ["customXml/item#{item[:index]}.xml"]
-            if item[:props_xml]
-              paths << "customXml/itemProps#{item[:index]}.xml"
-            end
-            paths
-          end
-        end
-
-        # Paths emitted from the document model: media, charts,
-        # embeddings, headers and footers (unified part store).
-        def document_part_paths
-          doc = package.document
-          return [] unless doc
-
-          media_chart_paths(doc) + header_footer_paths(doc)
-        end
-
-        def media_chart_paths(doc)
-          paths = [doc.image_parts, doc.chart_parts].compact.flat_map do |parts|
-            parts.values.map { |data| "word/#{data[:target]}" }
-          end
-          paths.concat(embedding_paths)
-        end
-
-        def embedding_paths
-          (package.embeddings || {}).keys.map { |target| "word/#{target}" }
-        end
-
-        def header_footer_paths(doc)
-          doc.header_footer_parts.filter_map do |part|
-            part.target && "word/#{part.target}"
-          end
+          Ooxml::PartRegistry.emitted_paths(package)
         end
 
         # -- Traversal helpers --

data/lib/uniword/docx.rb

@@ -9,7 +9,9 @@ module Uniword
   module Docx
     autoload :IdAllocator, "#{__dir__}/docx/id_allocator"
     autoload :Part, "#{__dir__}/docx/part"
+    autoload :RawPart, "#{__dir__}/docx/raw_part"
     autoload :ChartPart, "#{__dir__}/docx/chart_part"
+    autoload :ImagePart, "#{__dir__}/docx/image_part"
     autoload :HeaderFooterPart, "#{__dir__}/docx/header_footer_part"
     autoload :CustomXmlItem, "#{__dir__}/docx/custom_xml_item"
     autoload :PartCollection, "#{__dir__}/docx/part_collection"
@@ -21,6 +23,7 @@ module Uniword
     autoload :PackageIntegrityChecker,
              "#{__dir__}/docx/package_integrity_checker"
     autoload :PackageSerialization, "#{__dir__}/docx/package_serialization"
+    autoload :PartLoader, "#{__dir__}/docx/part_loader"
     autoload :Profile, "#{__dir__}/docx/profile"
     autoload :DocumentStatistics, "#{__dir__}/docx/document_statistics"
     autoload :Reconciler, "#{__dir__}/docx/reconciler"

data/lib/uniword/images/image_manager.rb

@@ -7,9 +7,9 @@ module Uniword
   module Images
     # Orchestrator for image operations on a DocumentRoot.
     #
-    # Works with the document's +image_parts+ hash (populated during DOCX
-    # loading) and the package ZIP to enumerate, extract, insert, and
-    # remove images.
+    # Works with the document's +image_parts+ collection (populated
+    # during DOCX loading) and the package ZIP to enumerate, extract,
+    # insert, and remove images.
     #
     # @example List images
     #   doc = Uniword::DocumentFactory.from_file("report.docx")
@@ -50,15 +50,15 @@ module Uniword
         parts = @document.image_parts
         return [] unless parts && !parts.empty?
 
-        parts.map do |_r_id, entry|
-          data = entry[:data]
+        parts.map do |_r_id, part|
+          data = part.data
           px_w, px_h = detect_pixel_dimensions(data) if data
-          name = File.basename(entry[:target].to_s)
+          name = File.basename(part.target.to_s)
 
           ImageInfo.new(
             name: name,
-            path: "word/#{entry[:target]}",
-            content_type: entry[:content_type].to_s,
+            path: "word/#{part.target}",
+            content_type: part.content_type.to_s,
             size: data ? data.bytesize : 0,
             width: px_w,
             height: px_h,
@@ -79,11 +79,11 @@ module Uniword
         parts = @document.image_parts
         return 0 unless parts && !parts.empty?
 
-        parts.each_value do |entry|
-          data = entry[:data]
+        parts.each_value do |part|
+          data = part.data
           next unless data
 
-          filename = File.basename(entry[:target].to_s)
+          filename = File.basename(part.target.to_s)
           File.binwrite(File.join(output_dir, filename), data)
         end
 
@@ -160,8 +160,8 @@ module Uniword
         parts = @document.image_parts
         return false unless parts && !parts.empty?
 
-        key = parts.find do |_k, entry|
-          File.basename(entry[:target].to_s) == image_name
+        key = parts.find do |_k, part|
+          File.basename(part.target.to_s) == image_name
         end&.first
 
         return false unless key

data/lib/uniword/ooxml/element_order.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Ooxml
+    # Safe mutation of lutaml-model `element_order` arrays.
+    #
+    # lutaml-model freezes `element_order` on parsed models; mutating
+    # it raises FrozenError. These helpers thaw on demand (dup +
+    # assign back) and insert entries in schema position — the single
+    # mechanism for the whole library, not a monkey-patch.
+    #
+    # @example Thaw and append
+    #   order = Ooxml::ElementOrder.mutable_order(footnotes)
+    #   order << Lutaml::Xml::Element.new("Element", "footnote")
+    #
+    # @example Idempotent singleton insert
+    #   Ooxml::ElementOrder.insert_once(settings, "updateFields",
+    #                                    after: "characterSpacingControl")
+    module ElementOrder
+      # Return the model's element_order as a mutable array.
+      #
+      # The frozen parsed array is replaced by a dup assigned back to
+      # the model; already-mutable arrays are returned as-is (so
+      # repeated calls keep mutating the same registered array).
+      #
+      # @param model [Lutaml::Model::Serializable] model to thaw
+      # @return [Array, nil] mutable element_order, or nil when the
+      #   model carries none
+      def mutable_order(model)
+        order = model.element_order
+        return unless order
+        return order unless order.frozen?
+
+        model.element_order = order.dup
+      end
+      module_function :mutable_order
+
+      # Append an entry (repeatable elements allowed).
+      #
+      # @param model [Lutaml::Model::Serializable] model to mutate
+      # @param entry [Lutaml::Xml::Element] entry to append
+      # @return [Array, nil] the mutated order
+      def append(model, entry)
+        mutable_order(model)&.<<(entry)
+      end
+      module_function :append
+
+      # Insert an entry at an index (repeatable elements allowed).
+      #
+      # @param model [Lutaml::Model::Serializable] model to mutate
+      # @param position [Integer] insertion index
+      # @param entry [Lutaml::Xml::Element] entry to insert
+      # @return [Array, nil] the mutated order
+      def insert_at(model, position, entry)
+        mutable_order(model)&.insert(position, entry)
+      end
+      module_function :insert_at
+
+      # Insert a singleton element in schema position, by name.
+      # Idempotent: no-op when an entry of that name already exists.
+      # Missing anchors fall back to end (after:) or start (before:).
+      #
+      # @param model [Lutaml::Model::Serializable] model to mutate
+      # @param name [String] element name to insert
+      # @param after [String, nil] insert after this element name
+      # @param before [String, nil] insert before this element name
+      # @param position [Integer, nil] explicit index (when neither
+      #   after nor before is given; defaults to end)
+      # @return [Array, nil] the mutated order
+      def insert_once(model, name, after: nil, before: nil, position: nil)
+        order = mutable_order(model)
+        return unless order
+        return if order.any? { |e| e.name == name }
+
+        idx = insertion_index(order, after, before, position)
+        order.insert(idx, Lutaml::Xml::Element.new("Element", name))
+      end
+      module_function :insert_once
+
+      # @return [Integer] index for the insert
+      def insertion_index(order, after, before, position)
+        if after
+          anchor = order.index { |e| e.name == after }
+          anchor ? anchor + 1 : order.size
+        elsif before
+          order.index { |e| e.name == before } || 0
+        else
+          position || order.size
+        end
+      end
+      module_function :insertion_index
+    end
+  end
+end