uniword 1.2.5 → 1.4.0

data/lib/uniword/docx/header_footer_part_collection.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Ordered collection of HeaderFooterPart objects — the single
+    # storage path for all header/footer parts of a document, whether
+    # loaded from an existing DOCX or added programmatically.
+    #
+    # The +headers+/+footers+ views (HeaderFooterView) and the
+    # serializer both read from this store, so a part exists exactly
+    # once: one part file, one relationship, one content-type
+    # override, one sectPr reference.
+    class HeaderFooterPartCollection
+      include Enumerable
+
+      def initialize
+        @parts = []
+      end
+
+      # Iterate over all parts (both kinds) in insertion order.
+      def each(&block)
+        @parts.each(&block)
+      end
+
+      # @return [Integer]
+      def size
+        @parts.size
+      end
+
+      alias length size
+
+      # @return [Boolean]
+      def empty?
+        @parts.empty?
+      end
+
+      # @return [Array<HeaderFooterPart>]
+      def to_a
+        @parts.dup
+      end
+
+      # Append a part.
+      #
+      # @param part [HeaderFooterPart]
+      # @return [HeaderFooterPart] the added part
+      def <<(part)
+        @parts << part
+        part
+      end
+
+      alias add <<
+
+      # Remove a part (by identity).
+      #
+      # @param part [HeaderFooterPart]
+      # @return [HeaderFooterPart, nil] the removed part
+      def delete(part)
+        @parts.delete(part)
+      end
+
+      # @param kind [Symbol] :header or :footer
+      # @return [Array<HeaderFooterPart>] parts of that kind, in order
+      def of_kind(kind)
+        @parts.select { |part| part.kind == kind }
+      end
+
+      # @param kind [Symbol] :header or :footer
+      # @param type [String, nil] sectPr reference type
+      # @return [HeaderFooterPart, nil]
+      def find_part(kind, type)
+        type = type&.to_s
+        @parts.find { |part| part.kind == kind && part.type == type }
+      end
+
+      # All non-nil relationship targets in the store.
+      #
+      # @return [Array<String>]
+      def targets
+        @parts.filter_map(&:target)
+      end
+
+      # First unused numbered target for a kind
+      # ("header3.xml" when header1/header2 exist).
+      #
+      # @param kind [Symbol] :header or :footer
+      # @return [String]
+      def next_target(kind)
+        numbers = of_kind(kind).filter_map do |part|
+          part.target&.[](/\A#{kind}(\d+)\.xml\z/, 1)&.to_i
+        end
+        "#{kind}#{(numbers.max || 0) + 1}.xml"
+      end
+
+      # Replace the entire store (legacy +header_footer_parts=+
+      # assignment). Accepts HeaderFooterPart objects and legacy
+      # part hashes ({ r_id:, target:, rel_type:, content_type:,
+      # content: }).
+      #
+      # @param parts [Array<HeaderFooterPart, Hash>]
+      # @return [void]
+      def replace_all(parts)
+        @parts = Array(parts).map { |part| self.class.wrap(part) }
+      end
+
+      # Replace all parts of one kind, leaving the other untouched.
+      #
+      # @param kind [Symbol] :header or :footer
+      # @param parts [Array<HeaderFooterPart>]
+      # @return [void]
+      def replace_kind(kind, parts)
+        @parts.reject! { |part| part.kind == kind }
+        parts.each { |part| @parts << part }
+      end
+
+      # Normalize one entry into a HeaderFooterPart. Legacy hashes
+      # describe loaded parts (they carry original rIds/targets).
+      #
+      # @param value [HeaderFooterPart, Hash]
+      # @return [HeaderFooterPart]
+      def self.wrap(value)
+        return value if value.is_a?(HeaderFooterPart)
+
+        HeaderFooterPart.new(
+          r_id: value[:r_id],
+          target: value[:target],
+          rel_type: value[:rel_type],
+          content_type: value[:content_type],
+          type: value[:type],
+          content: value[:content],
+          loaded: true,
+        )
+      end
+    end
+  end
+end

data/lib/uniword/docx/header_footer_view.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Kind-filtered view over a document's HeaderFooterPartCollection.
+    #
+    # +document.headers+ and +document.footers+ return these views, so
+    # the Builder, the headers/footers managers and the serializer all
+    # share the single underlying store.
+    #
+    # Two historic access shapes are preserved:
+    # - Hash-style (Builder): +view["default"] = header_model+,
+    #   +view["default"]+, +each_value+, +values+, +keys+, +key?+,
+    #   +delete+. Content access yields the Header/Footer models.
+    # - Array-style (managers): +view << header+, +each+, +map+,
+    #   +find+, +reject+. Iteration yields HeaderFooterPart objects,
+    #   which carry the sectPr +type+ and delegate +paragraphs+,
+    #   +tables+ and +empty?+ to their content.
+    #
+    # Upsert semantics: assigning a type that already exists replaces
+    # that part's content in place (keeping its target and rId), so
+    # loaded and builder-created parts can never duplicate.
+    class HeaderFooterView
+      include Enumerable
+
+      # @return [Symbol] :header or :footer
+      attr_reader :kind
+
+      # @param store [HeaderFooterPartCollection] the unified store
+      # @param kind [Symbol] :header or :footer
+      def initialize(store, kind)
+        @store = store
+        @kind = kind
+      end
+
+      # Iterate over the parts of this kind (Array-style access).
+      def each(&block)
+        @store.of_kind(kind).each(&block)
+      end
+
+      # Hash-style read: content model for a sectPr type.
+      #
+      # @param type [String, Symbol] "default"/"first"/"even"
+      # @return [Wordprocessingml::Header, Wordprocessingml::Footer, nil]
+      def [](type)
+        @store.find_part(kind, type)&.content
+      end
+
+      # Hash-style write: upsert a content model by sectPr type.
+      # Replaces the existing part's content in place when the type
+      # exists; otherwise appends a new part with the next free
+      # numbered target.
+      #
+      # @param type [String, Symbol] sectPr reference type
+      # @param model [Object] Wordprocessingml::Header/Footer or
+      #   legacy Uniword::Header/Footer
+      # @return [Object] the assigned model
+      def []=(type, model)
+        type = type.to_s
+        content = coerce_content(model)
+        part = @store.find_part(kind, type)
+        if part
+          part.content = content
+          part.loaded = false
+        else
+          @store << HeaderFooterPart.new(
+            kind: kind, type: type, content: content,
+            target: @store.next_target(kind)
+          )
+        end
+        model
+      end
+
+      # Append a model (Array-style). Legacy Uniword::Header/Footer
+      # models supply their own +type+; other models are stored
+      # without a type.
+      #
+      # @param model [Object] content model or HeaderFooterPart
+      # @return [Object] the appended model
+      def <<(model)
+        if model.is_a?(HeaderFooterPart)
+          adopt_part(model)
+        else
+          append_model(model)
+        end
+        model
+      end
+
+      # Iterate over sectPr types.
+      def each_key(&block)
+        map(&:type).each(&block)
+      end
+
+      # Iterate over content models.
+      def each_value(&block)
+        map(&:content).each(&block)
+      end
+
+      # @return [Array<String, nil>] sectPr types
+      def keys
+        map(&:type)
+      end
+
+      # @return [Array] content models
+      def values
+        map(&:content)
+      end
+
+      # @param type [String, Symbol]
+      # @return [Boolean]
+      def key?(type)
+        !@store.find_part(kind, type).nil?
+      end
+
+      # Remove the part for a sectPr type.
+      #
+      # @param type [String, Symbol]
+      # @return [Object, nil] the removed part's content
+      def delete(type)
+        part = @store.find_part(kind, type)
+        return nil unless part
+
+        @store.delete(part)
+        part.content
+      end
+
+      # @return [Integer]
+      def size
+        @store.of_kind(kind).size
+      end
+
+      # @return [Boolean]
+      def empty?
+        size.zero?
+      end
+
+      # Bulk assignment (+document.headers = value+). Accepts nil
+      # (clears this kind), a Hash of type => model, an Array of
+      # models/parts, or the view itself (no-op).
+      #
+      # @param value [nil, Hash, Array, HeaderFooterView]
+      # @return [Object] the assigned value
+      def replace(value)
+        case value
+        when nil then @store.replace_kind(kind, [])
+        when HeaderFooterView then nil
+        when Hash then replace_from_hash(value)
+        when Array then replace_from_array(value)
+        else
+          raise ArgumentError,
+                "cannot assign #{value.class} to document.#{kind}s"
+        end
+        value
+      end
+
+      private
+
+      def adopt_part(part)
+        part.target ||= @store.next_target(part.kind || kind)
+        @store << part
+      end
+
+      def append_model(model)
+        type = legacy_type(model)
+        return self[type] = model if type
+
+        @store << HeaderFooterPart.new(
+          kind: kind, content: coerce_content(model),
+          target: @store.next_target(kind)
+        )
+      end
+
+      def replace_from_hash(hash)
+        hash.each { |type, model| self[type] = model }
+        kept = hash.keys.map(&:to_s)
+        @store.of_kind(kind).each do |part|
+          @store.delete(part) if stale_fresh_part?(part, kept)
+        end
+      end
+
+      # A programmatically-added part is stale after a Hash assignment
+      # when its type is not among the assigned keys (loaded parts are
+      # never removed by view assignment).
+      def stale_fresh_part?(part, kept_types)
+        !part.loaded? && !part.type.nil? && !kept_types.include?(part.type)
+      end
+
+      def replace_from_array(array)
+        parts = array.map { |entry| coerce_to_part(entry) }
+        @store.replace_kind(kind, [])
+        parts.each do |part|
+          part.target ||= @store.next_target(kind)
+          @store << part
+        end
+      end
+
+      def coerce_to_part(entry)
+        case entry
+        when HeaderFooterPart then entry
+        when Hash then HeaderFooterPartCollection.wrap(entry)
+        else
+          HeaderFooterPart.new(
+            kind: kind, type: legacy_type(entry),
+            content: coerce_content(entry)
+          )
+        end
+      end
+
+      # Legacy Uniword::Header/Footer carry their sectPr type.
+      def legacy_type(model)
+        case model
+        when Uniword::Header, Uniword::Footer then model.type
+        end
+      end
+
+      # Content is stored as given: legacy Uniword::Header/Footer
+      # models stay live (callers may keep mutating them) and are
+      # converted to their Wordprocessingml counterparts only at
+      # serialization time (HeaderFooterPart#serializable_content).
+      def coerce_content(model)
+        model
+      end
+    end
+  end
+end

data/lib/uniword/docx/id_allocator.rb

@@ -17,22 +17,32 @@ module Uniword
     #
     # This is the "populate-first" principle: when loading a template DOCX,
     # parse and seed ALL existing IDs from the template before modification.
+    #
+    # rId namespaces are per relationships part: "rId1" in _rels/.rels and
+    # "rId1" in word/_rels/document.xml.rels do not collide. The allocator
+    # therefore tracks rIds per +scope+ (:document for document-level rels,
+    # :package for package-level rels); each scope has its own registry,
+    # counter and uniqueness domain.
     class IdAllocator
-      REL_TYPE_BASE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
-
-      IMAGE_REL_TYPE = "#{REL_TYPE_BASE}/image"
-      HEADER_REL_TYPE = "#{REL_TYPE_BASE}/header"
-      FOOTER_REL_TYPE = "#{REL_TYPE_BASE}/footer"
-      HYPERLINK_REL_TYPE = "#{REL_TYPE_BASE}/hyperlink"
-      CHART_REL_TYPE = "#{REL_TYPE_BASE}/chart"
-      FOOTNOTES_REL_TYPE = "#{REL_TYPE_BASE}/footnotes"
-      ENDNOTES_REL_TYPE = "#{REL_TYPE_BASE}/endnotes"
-      THEME_REL_TYPE = "#{REL_TYPE_BASE}/theme"
-      NUMBERING_REL_TYPE = "#{REL_TYPE_BASE}/numbering"
+      # Relationship type namespace base (also the r: namespace URI).
+      # Individual rel type constants derive from Ooxml::PartRegistry,
+      # the single source of truth for part metadata.
+      REL_TYPE_BASE = Ooxml::PartRegistry::OFFICE_REL_BASE
+
+      IMAGE_REL_TYPE = Ooxml::PartRegistry.find_by_key(:image).rel_type
+      HEADER_REL_TYPE = Ooxml::PartRegistry.find_by_key(:header).rel_type
+      FOOTER_REL_TYPE = Ooxml::PartRegistry.find_by_key(:footer).rel_type
+      HYPERLINK_REL_TYPE = Ooxml::PartRegistry.find_by_key(:hyperlink).rel_type
+      CHART_REL_TYPE = Ooxml::PartRegistry.find_by_key(:chart).rel_type
+      FOOTNOTES_REL_TYPE = Ooxml::PartRegistry.find_by_key(:footnotes).rel_type
+      ENDNOTES_REL_TYPE = Ooxml::PartRegistry.find_by_key(:endnotes).rel_type
+      THEME_REL_TYPE = Ooxml::PartRegistry.find_by_key(:theme).rel_type
+      NUMBERING_REL_TYPE = Ooxml::PartRegistry.find_by_key(:numbering).rel_type
 
       def initialize
-        @rid_counter = 0
-        @rid_entries = {}  # [target, type] -> { id, type, target, target_mode }
+        @rid_counters = Hash.new(0) # scope -> high-water mark
+        # [scope, target, type] -> { id, type, target, target_mode, scope }
+        @rid_entries = {}
         @footnote_counter = 1
         @endnote_counter = 1
         @bookmark_counter = 0
@@ -43,16 +53,56 @@ module Uniword
 
       # Allocate a relationship ID for a target+type pair.
       # Returns existing rId if this target+type was already registered.
-      def alloc_rid(target:, type:, target_mode: nil)
-        key = [target, type.to_s]
+      #
+      # @param target [String] relationship target
+      # @param type [String] relationship type
+      # @param target_mode [String, nil] e.g. "External"
+      # @param scope [Symbol] :document or :package (rels part namespace)
+      # @return [String] the allocated (or existing) rId
+      def alloc_rid(target:, type:, target_mode: nil, scope: :document)
+        key = [scope, target, type.to_s]
         @rid_entries[key] ||= begin
-          @rid_counter += 1
-          { id: "rId#{@rid_counter}", type: type.to_s,
-            target: target, target_mode: target_mode }
+          @rid_counters[scope] += 1
+          @rid_counters[scope] += 1 while rid_id_taken?(
+            "rId#{@rid_counters[scope]}", scope
+          )
+          { id: "rId#{@rid_counters[scope]}", type: type.to_s,
+            target: target, target_mode: target_mode, scope: scope }
         end
         @rid_entries[key][:id]
       end
 
+      # Register an explicit rId for a target+type pair.
+      # Used when a relationship id is assigned outside the counter
+      # (rId dedup repair) so later lookups stay consistent.
+      #
+      # @param id [String] relationship ID to register
+      # @param target [String] relationship target
+      # @param type [String] relationship type
+      # @param target_mode [String, nil] e.g. "External"
+      # @param scope [Symbol] :document or :package
+      # @return [String] the registered id
+      def register_rid(id, target:, type:, target_mode: nil, scope: :document)
+        @rid_entries[[scope, target, type.to_s]] = {
+          id: id, type: type.to_s, target: target, target_mode: target_mode,
+          scope: scope
+        }
+        num = id[/\ArId(\d+)\z/, 1]&.to_i || 0
+        @rid_counters[scope] = [@rid_counters[scope], num].max
+        id
+      end
+
+      # The next free rId past the high-water mark of a scope —
+      # guaranteed not registered to any target+type in that scope.
+      #
+      # @param scope [Symbol] :document or :package
+      # @return [String] e.g. "rId7"
+      def next_free_rid(scope: :document)
+        candidate = @rid_counters[scope] + 1
+        candidate += 1 while rid_id_taken?("rId#{candidate}", scope)
+        "rId#{candidate}"
+      end
+
       def alloc_footnote_id
         id = @footnote_counter
         @footnote_counter += 1
@@ -85,21 +135,19 @@ module Uniword
         Digest::SHA256.hexdigest("rsid:#{@rsid_counter}").upcase[0, 8]
       end
 
-      # Seed from a relationships collection — preserves existing rIds.
-      def seed_from_rels(relationships)
+      # Seed from a relationships collection — preserves existing rIds
+      # verbatim so a load→save round-trip is rId-stable. A loaded rId
+      # already registered to a different target+type in the same scope
+      # (only possible when allocation preceded seeding, or the source
+      # has duplicate ids) yields a fresh counter allocation for the
+      # seeded pair instead — uniqueness wins over verbatim preservation.
+      #
+      # @param relationships [Array, nil] rels to seed
+      # @param scope [Symbol] :document or :package (rels part namespace)
+      def seed_from_rels(relationships, scope: :document)
         return unless relationships
 
-        relationships.each do |r|
-          key = [r.target, r.type.to_s]
-          @rid_entries[key] = {
-            id: r.id,
-            type: r.type.to_s,
-            target: r.target,
-            target_mode: r.target_mode,
-          }
-          num = r.id[/\ArId(\d+)\z/, 1]&.to_i || 0
-          @rid_counter = [@rid_counter, num].max
-        end
+        relationships.each { |r| seed_rel(r, scope) }
       end
 
       # Seed footnote/endnote counters from existing note entries.
@@ -114,14 +162,26 @@ module Uniword
         end
       end
 
+      # Seed the comment counter from existing comment entries so newly
+      # allocated comment IDs do not collide with loaded ones.
+      def seed_from_comments(comments)
+        comments&.each do |c|
+          @comment_counter = [@comment_counter, c.comment_id.to_i].max
+        end
+      end
+
       # Produce the final ordered list of all allocated relationships.
-      def all_rels
-        @rid_entries.values.sort_by { |r| r[:id][/\d+/]&.to_i || 0 }
+      #
+      # @param scope [Symbol, nil] restrict to one scope; nil for all
+      def all_rels(scope: nil)
+        entries = @rid_entries.values
+        entries = entries.select { |r| r[:scope] == scope } if scope
+        entries.sort_by { |r| r[:id][/\d+/]&.to_i || 0 }
       end
 
       # Check if a relationship has been registered for a target+type.
-      def rid_for(target:, type:)
-        key = [target, type.to_s]
+      def rid_for(target:, type:, scope: :document)
+        key = [scope, target, type.to_s]
         @rid_entries[key]&.fetch(:id, nil)
       end
 
@@ -131,13 +191,47 @@ module Uniword
       def self.populate_from_package(package)
         alloc = new
         alloc.seed_from_rels(package.document_rels&.relationships)
-        alloc.seed_from_rels(package.package_rels&.relationships)
+        alloc.seed_from_rels(package.package_rels&.relationships,
+                             scope: :package)
         alloc.seed_from_notes(
           package.footnotes&.footnote_entries,
           package.endnotes&.endnote_entries,
         )
+        alloc.seed_from_comments(comment_entries_of(package))
         alloc
       end
+
+      # Comment entries of a package or document, tolerating the legacy
+      # Array form of DocumentRoot#comments.
+      def self.comment_entries_of(source)
+        part = source.comments
+        part.is_a?(Uniword::CommentsPart) ? part.comments : part
+      end
+      private_class_method :comment_entries_of
+
+      private
+
+      # Seed one relationship (see seed_from_rels for the collision rule).
+      def seed_rel(rel, scope)
+        key = [scope, rel.target, rel.type.to_s]
+        return if @rid_entries.key?(key)
+
+        if rid_id_taken?(rel.id, scope)
+          alloc_rid(target: rel.target, type: rel.type,
+                    target_mode: rel.target_mode, scope: scope)
+          return
+        end
+
+        register_rid(rel.id, target: rel.target, type: rel.type,
+                           target_mode: rel.target_mode, scope: scope)
+      end
+
+      # Whether an rId string is already registered within a scope.
+      def rid_id_taken?(id, scope)
+        @rid_entries.any? do |key, entry|
+          key[0] == scope && entry[:id] == id
+        end
+      end
     end
   end
 end

data/lib/uniword/docx/image_part.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # An image part (word/media/*) held by the package: binary image
+    # data plus the packaging metadata needed to emit it (relationship
+    # target, relationship id, content type).
+    #
+    # The image content type is per-file (resolved from the file
+    # extension), so it is always carried explicitly — the registry's
+    # :image definition contributes only the relationship type.
+    #
+    # Replaces the raw +{ data:, target:, content_type:, path: }+ hash
+    # entries formerly stored in +DocumentRoot#image_parts+. Hash-style
+    # read access (+part[:data]+, +part[:target]+, +part[:content_type]+,
+    # +part[:path]+) is kept for backward compatibility.
+    #
+    # @example
+    #   part = ImagePart.new(
+    #     r_id: "rId5", target: "media/image1.png",
+    #     data: binary_data, content_type: "image/png",
+    #   )
+    #   part.data         # => binary image data
+    #   part.content_type # => "image/png"
+    class ImagePart < Part
+      # @return [String, nil] path of the source file the image was
+      #   read from (builder-added images only; nil for loaded parts)
+      attr_accessor :source_path
+
+      # @param r_id [String, nil] relationship id
+      # @param target [String, nil] e.g. "media/image1.png"
+      # @param data [String, nil] binary image data
+      # @param content_type [String, nil] e.g. "image/png"
+      # @param source_path [String, nil] on-disk source path
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(r_id: nil, target: nil, data: nil, content_type: nil,
+                     source_path: nil, **rest)
+        super(
+          definition: Ooxml::PartRegistry.find_by_key(:image),
+          r_id: r_id, target: target, content: data,
+          content_type: content_type, **rest
+        )
+        @source_path = source_path
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Wrap a legacy raw-hash entry ({ data:, target:, content_type:,
+      # path: }) into an ImagePart.
+      #
+      # @param hash [Hash] legacy hash entry
+      # @return [ImagePart]
+      def self.from_hash(hash)
+        new(target: hash[:target], data: hash[:data],
+            content_type: hash[:content_type], source_path: hash[:path])
+      end
+
+      # Binary image data (alias for content).
+      #
+      # @return [String, nil]
+      def data
+        content
+      end
+
+      # Set the binary image data (alias for content=).
+      #
+      # @param value [String, nil] binary image data
+      # @return [void]
+      def data=(value)
+        self.content = value
+      end
+
+      # Hash-style read compatibility (+:data+ and the legacy +:path+
+      # source path in addition to the Part keys).
+      def [](key)
+        case key.to_sym
+        when :data then content
+        when :path then source_path
+        else super
+        end
+      end
+    end
+  end
+end