uniword 1.2.5 → 1.4.0

data/lib/uniword/docx/part_collection.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Keyed collection of Docx::Part objects.
+    #
+    # Backs +chart_parts+ (keyed by relationship id) and +embeddings+
+    # (keyed by relationship target). Keeps the legacy Hash-like
+    # access patterns working: assignment accepts Part objects, the
+    # former raw hashes ({ xml:, target: }) and raw content Strings,
+    # normalizing them into Part objects.
+    #
+    # @example
+    #   parts = PartCollection.new(:r_id)
+    #   parts["rIdChart1"] = { xml: "...", target: "charts/chart1.xml" }
+    #   parts.values.first[:target] # => "charts/chart1.xml"
+    class PartCollection
+      include Enumerable
+
+      # @param key_attribute [Symbol] part attribute serving as the
+      #   collection key (:r_id for charts, :target for embeddings)
+      # @param part_class [Class] Part subclass used to wrap raw values
+      def initialize(key_attribute, part_class)
+        @key_attribute = key_attribute
+        @part_class = part_class
+        @parts = {}
+      end
+
+      # @param key [String] collection key (rId or target)
+      # @return [Part, nil]
+      def [](key)
+        @parts[key]
+      end
+
+      # Store a part, normalizing raw hashes and raw content.
+      #
+      # @param key [String] collection key
+      # @param value [Part, Hash, String]
+      def []=(key, value)
+        @parts[key] = wrap(key, value)
+      end
+
+      # Iterate over [key, Part] pairs.
+      def each(&block)
+        @parts.each(&block)
+      end
+
+      # Iterate over collection keys.
+      def each_key(&block)
+        @parts.each_key(&block)
+      end
+
+      # Iterate over stored parts.
+      def each_value(&block)
+        @parts.each_value(&block)
+      end
+
+      # @return [Array<Part>]
+      def values
+        @parts.values
+      end
+
+      # @return [Array<String>]
+      def keys
+        @parts.keys
+      end
+
+      # @return [Integer]
+      def size
+        @parts.size
+      end
+
+      # @return [Boolean]
+      def empty?
+        @parts.empty?
+      end
+
+      # @return [Boolean]
+      def key?(key)
+        @parts.key?(key)
+      end
+
+      # Hash-style alias for key? (RSpec's have_key matcher, legacy
+      # callers).
+      alias has_key? key?
+
+      # @return [Part, nil] the removed part
+      def delete(key)
+        @parts.delete(key)
+      end
+
+      # Replace the whole collection from a Hash (or another
+      # PartCollection); nil clears it.
+      #
+      # @param value [Hash, PartCollection, nil]
+      # @return [void]
+      def replace_all(value)
+        @parts.clear
+        return if value.nil?
+
+        value.each { |key, part| self[key] = part }
+      end
+
+      # Key attribute => assigner lambda filling the attribute from
+      # the collection key when the part does not carry it.
+      KEY_ASSIGNERS = {
+        r_id: ->(part, key) { part.r_id ||= key },
+        target: ->(part, key) { part.target ||= key },
+        path: ->(part, key) { part.path ||= key },
+      }.freeze
+
+      private
+
+      def wrap(key, value)
+        case value
+        when Part
+          value
+        when Hash
+          @part_class.from_hash(value).tap { |part| assign_key(part, key) }
+        else
+          @part_class.new(content: value).tap { |part| assign_key(part, key) }
+        end
+      end
+
+      def assign_key(part, key)
+        assigner = KEY_ASSIGNERS[@key_attribute]
+        assigner&.call(part, key.to_s)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads chart parts (word/charts/chartN.xml) into the document's
+      # chart_parts collection, keyed by the id of the document
+      # relationship targeting each chart. Charts without a matching
+      # document relationship are skipped.
+      class ChartLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :chart
+        # @return [void]
+        def load(context, definition)
+          package = context.package
+          return unless package.document_rels
+
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          paths.each do |path|
+            load_chart(context, definition, path)
+          end
+        end
+
+        private
+
+        def load_chart(context, definition, path)
+          target = path.delete_prefix("word/")
+          rel = find_chart_relationship(context.package, definition, target)
+          return unless rel
+
+          context.package.document.chart_parts[rel.id] = ChartPart.new(
+            r_id: rel.id,
+            target: target,
+            content: context.zip_content[path],
+          )
+        end
+
+        # The document relationship of the definition's type targeting
+        # the chart, or nil when none targets it.
+        def find_chart_relationship(package, definition, target)
+          package.document_rels.relationships.find do |r|
+            r.target == target && r.type.to_s.include?(definition.rel_type)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads customXml data items (customXml/itemN.xml) together with
+      # their itemProps and relationships sidecars into
+      # CustomXmlItem objects on the package.
+      class CustomXmlLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :custom_xml_item
+        # @return [void]
+        def load(context, definition)
+          item_paths = context.matching_paths(definition)
+          return if item_paths.empty?
+
+          items = item_paths.sort_by { |path| item_index(path) }.map do |path|
+            build_item(context, path)
+          end
+          context.package.custom_xml_items = items
+        end
+
+        private
+
+        def build_item(context, item_path)
+          index = item_index(item_path)
+          CustomXmlItem.new(
+            index: index,
+            xml_content: context.zip_content[item_path],
+            props_xml: context.zip_content[props_path(index)],
+            rels_xml: context.zip_content[sidecar_rels_path(item_path)],
+          )
+        end
+
+        def item_index(path)
+          path[/item(\d+)/, 1].to_i
+        end
+
+        def props_path(index)
+          Ooxml::PartRegistry.find_by_key(:custom_xml_item_props)
+            .path_for(index: index)
+        end
+
+        # OPC relationships sidecar of the item part
+        # ("customXml/item1.xml" → "customXml/_rels/item1.xml.rels").
+        def sidecar_rels_path(item_path)
+          File.join(File.dirname(item_path), "_rels",
+                    "#{File.basename(item_path)}.rels")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads OLE/embedded object binaries (word/embeddings/*) into
+      # the package's embeddings collection, keyed by relationship
+      # target (path relative to word/).
+      class EmbeddingLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :ole_object
+        # @return [void]
+        def load(context, definition)
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          embeddings = context.package.embeddings
+          paths.each do |path|
+            embeddings[path.delete_prefix("word/")] =
+              context.zip_content[path]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads header and footer parts (word/headerN.xml,
+      # word/footerN.xml) into HeaderFooterPart objects on the
+      # document's unified header/footer store. Registered under the
+      # :header_footer loader key for both the :header and :footer
+      # definitions; the definition selects kind, path pattern,
+      # relationship type, and content model.
+      #
+      # Each part keeps its loaded relationship id, target, and
+      # rel_type verbatim, plus the sectPr reference type
+      # ("default"/"first"/"even") collected from every section
+      # properties element, so the save path can leave loaded
+      # relationships untouched.
+      class HeaderFooterLoader
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :header or :footer
+        # @return [void]
+        def load(context, definition)
+          package = context.package
+          return unless package.document && package.document_rels
+
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          load_parts(context, definition, package, paths.sort)
+        end
+
+        private
+
+        # Parse each path and append its part to the document's
+        # header/footer store.
+        def load_parts(context, definition, package, paths)
+          ref_types = reference_types(package.document)
+          store = package.document.header_footer_parts
+          paths.each do |path|
+            part = build_part(context, definition, path, ref_types)
+            store << part if part
+          end
+        end
+
+        # Build the part for one path, or nil when no document
+        # relationship of the definition's type targets it.
+        def build_part(context, definition, path, ref_types)
+          target = path.delete_prefix("word/")
+          rel = find_relationship(context.package, definition, target)
+          return nil unless rel
+
+          HeaderFooterPart.new(
+            kind: definition.key,
+            r_id: rel.id,
+            target: target,
+            rel_type: rel.type,
+            type: ref_types[rel.id],
+            content: definition.loader_model.from_xml(
+              context.zip_content[path],
+            ),
+            loaded: true,
+          )
+        end
+
+        def find_relationship(package, definition, target)
+          package.document_rels.relationships.find do |r|
+            r.target == target && r.type.to_s.include?(definition.rel_type)
+          end
+        end
+
+        # Map relationship id => sectPr reference type
+        # ("default"/"first"/"even") from every section properties
+        # element (body-level and paragraph-level).
+        def reference_types(document)
+          types = {}
+          section_properties_of(document).each do |sect_pr|
+            collect_reference_types(types, sect_pr.header_references)
+            collect_reference_types(types, sect_pr.footer_references)
+          end
+          types
+        end
+
+        def collect_reference_types(types, references)
+          (references || []).each do |ref|
+            types[ref.r_id] = ref.type if ref.r_id
+          end
+        end
+
+        def section_properties_of(document)
+          body = document.body
+          return [] unless body
+
+          from_paragraphs = (body.paragraphs || []).filter_map do |para|
+            para.properties&.section_properties
+          end
+          [body.section_properties, *from_paragraphs].compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Loads image parts (word/media/*) into the document's
+      # image_parts collection, keyed by the relationship id the loaded
+      # document rels assign to each media target so downstream
+      # consumers (MHTML rendering, image manager) resolve r:embed
+      # references correctly. Media with no document-level rel (e.g.
+      # theme-only images) gets a synthetic key; it never becomes a
+      # relationship.
+      #
+      # The content type is derived from the file extension; the
+      # extension mapping is wider than the registry's Default entries
+      # (bmp, tiff, svg) and preserved verbatim from the historic
+      # load path.
+      class ImageLoader
+        # Extension → content type mapping (wider than the registry's
+        # Default entries; preserved verbatim from the historic load
+        # path).
+        CONTENT_TYPES = {
+          "jpg" => "image/jpeg", "jpeg" => "image/jpeg",
+          "png" => "image/png", "gif" => "image/gif",
+          "bmp" => "image/bmp",
+          "tiff" => "image/tiff", "tif" => "image/tiff",
+          "svg" => "image/svg+xml"
+        }.freeze
+
+        # @param context [LoadContext] shared load state
+        # @param definition [Ooxml::PartDefinition] :image
+        # @return [void]
+        def load(context, definition)
+          package = context.package
+          return unless package.document
+
+          paths = context.matching_paths(definition)
+          return if paths.empty?
+
+          paths.each do |path|
+            load_image(context, definition, path)
+          end
+        end
+
+        private
+
+        def load_image(context, definition, path)
+          package = context.package
+          filename = File.basename(path)
+          r_id = loaded_image_rid(package, definition, filename) ||
+            next_synthetic_image_key(package)
+
+          package.document.image_parts[r_id] = ImagePart.new(
+            r_id: r_id,
+            data: binary_data(context, path),
+            target: "media/#{filename}",
+            content_type: content_type_for(filename),
+          )
+        end
+
+        # The rId a loaded document relationship assigns to
+        # "media/<filename>", or nil when no image rel targets it.
+        def loaded_image_rid(package, definition, filename)
+          rel = package.document_rels&.relationships&.find do |r|
+            r.target == "media/#{filename}" &&
+              r.type.to_s == definition.rel_type
+          end
+          rel&.id
+        end
+
+        # Synthetic image-part key that cannot collide with a loaded
+        # relationship id or an already-keyed image part.
+        def next_synthetic_image_key(package)
+          taken = package.document_rels&.relationships&.map(&:id) || []
+          n = package.document.image_parts.size + 1
+          n += 1 while taken.include?("rId#{n}")
+          "rId#{n}"
+        end
+
+        # Re-read bytes from the original ZIP when available (the
+        # extracted hash may carry corrupted UTF-8 binary).
+        def binary_data(context, path)
+          return context.zip_content[path] unless context.zip_path
+
+          read_binary_from_zip(context.zip_path, path)
+        end
+
+        def read_binary_from_zip(zip_path, entry_path)
+          require "zip"
+          Zip::File.open(zip_path) do |zip_file|
+            entry = zip_file.find_entry(entry_path)
+            return nil unless entry
+
+            entry.get_input_stream.read
+          end
+        end
+
+        def content_type_for(filename)
+          ext = File.extname(filename).delete(".").downcase
+          CONTENT_TYPES.fetch(ext, "image/#{ext}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class PartLoader
+      # Shared state for one package load: the extracted ZIP entries,
+      # the package being populated, and the main-document paths
+      # resolved from the package-level relationships.
+      class LoadContext
+        # @return [Hash] extracted ZIP entries (package path => content)
+        attr_reader :zip_content
+
+        # @return [Package] package being populated
+        attr_reader :package
+
+        # @return [String, nil] original ZIP path for binary
+        #   re-extraction
+        attr_reader :zip_path
+
+        # @param zip_content [Hash] extracted ZIP entries
+        # @param package [Package] package being populated
+        # @param zip_path [String, nil] original ZIP path
+        def initialize(zip_content:, package:, zip_path: nil)
+          @zip_content = zip_content
+          @package = package
+          @zip_path = zip_path
+        end
+
+        # Zip entry paths matching the definition's fixed path or
+        # path pattern (numbered part families).
+        #
+        # @param definition [Ooxml::PartDefinition]
+        # @return [Array<String>] in zip_content order
+        def matching_paths(definition)
+          zip_content.keys.select { |path| definition.match_path?(path) }
+        end
+
+        # Main document part path, resolved from the package-level
+        # officeDocument relationship.
+        #
+        # @return [String, nil] e.g. "word/document.xml"
+        def main_document_path
+          return @main_document_path if defined?(@main_document_path)
+
+          @main_document_path = find_main_document_path
+        end
+
+        # Relationships part path of the main document, derived from
+        # its resolved path.
+        #
+        # @return [String, nil] e.g. "word/_rels/document.xml.rels"
+        def main_document_rels_path
+          return @main_document_rels_path if defined?(@main_document_rels_path)
+
+          @main_document_rels_path = sidecar_rels_path(main_document_path)
+        end
+
+        private
+
+        def find_main_document_path
+          relationships = package.package_rels&.relationships
+          return nil unless relationships
+
+          office_document = Ooxml::PartRegistry.find_by_key(:document).rel_type
+          rel = relationships.find do |r|
+            r.type.to_s.include?(office_document)
+          end
+          return nil unless rel&.target
+
+          rel.target.dup.delete_prefix("/")
+        end
+
+        # OPC relationships sidecar: sibling "_rels" directory named
+        # after the part ("word/document.xml" →
+        # "word/_rels/document.xml.rels").
+        def sidecar_rels_path(part_path)
+          return nil unless part_path
+
+          File.join(File.dirname(part_path), "_rels",
+                    "#{File.basename(part_path)}.rels")
+        end
+      end
+    end
+  end
+end