uniword 1.0.11 → 1.2.4

data/lib/uniword/builder/footnote_builder.rb

@@ -5,25 +5,16 @@ module Uniword
     # Builds footnotes and endnotes for documents.
     #
     # Manages footnote/endnote creation, ID assignment, and wiring
-    # references into the document body.
-    #
-    # @example Add footnotes to a document
-    #   doc = DocumentBuilder.new
-    #   doc.paragraph { |p| p << 'See the '; p << doc.footnote('A note') }
-    #
-    # @example Add endnotes
-    #   doc.paragraph { |p| p << 'See '; p << doc.endnote('An endnote') }
+    # references into the document body. Uses IdAllocator for all ID
+    # assignment when available.
     class FootnoteBuilder
-      def initialize(document)
+      def initialize(document, allocator: nil)
         @document = document
+        @allocator = allocator
       end
 
       # Create a footnote and return a Run with a footnoteReference.
       #
-      # The footnote body is stored in the document's footnotes collection.
-      # The returned Run contains a <w:footnoteReference> element that
-      # Word uses to link to the footnote body.
-      #
       # @param text [String] Footnote text content
       # @yield [ParagraphBuilder] Builder for rich footnote content
       # @return [Wordprocessingml::Run] Run with footnote reference
@@ -61,24 +52,32 @@ module Uniword
       end
 
       def next_footnote_id
-        @footnote_counter ||= 1
-        id = @footnote_counter
-        @footnote_counter += 1
-        id
+        if @allocator
+          @allocator.alloc_footnote_id
+        else
+          @footnote_counter ||= 1
+          id = @footnote_counter
+          @footnote_counter += 1
+          id
+        end
       end
 
       def next_endnote_id
-        @endnote_counter ||= 1
-        id = @endnote_counter
-        @endnote_counter += 1
-        id
+        if @allocator
+          @allocator.alloc_endnote_id
+        else
+          @endnote_counter ||= 1
+          id = @endnote_counter
+          @endnote_counter += 1
+          id
+        end
       end
 
       def create_footnote_entry(id, text, &block)
         # OOXML spec: regular footnotes must NOT have w:type.
         # Only separator/continuationSeparator use w:type.
         entry = Wordprocessingml::Footnote.new(id: id.to_s)
-        para = ParagraphBuilder.new
+        para = ParagraphBuilder.new(allocator: @allocator)
         if block_given?
           block.call(para)
         elsif text
@@ -90,7 +89,7 @@ module Uniword
 
       def create_endnote_entry(id, text, &block)
         entry = Wordprocessingml::Endnote.new(id: id.to_s)
-        para = ParagraphBuilder.new
+        para = ParagraphBuilder.new(allocator: @allocator)
         if block_given?
           block.call(para)
         elsif text

data/lib/uniword/builder/header_footer_builder.rb

@@ -15,10 +15,11 @@ module Uniword
     #     f << Builder.page_number_field
     #   end
     class HeaderFooterBuilder
-      attr_reader :model, :kind
+      attr_reader :model, :kind, :allocator
 
-      def initialize(kind, type: "default")
+      def initialize(kind, type: "default", allocator: nil)
         @kind = kind
+        @allocator = allocator
         @model = if kind == :header
                    Wordprocessingml::Header.new
                  else
@@ -33,15 +34,14 @@ module Uniword
       def <<(element)
         case element
         when String
-          para = Wordprocessingml::Paragraph.new
-          para.runs << Wordprocessingml::Run.new(text: element)
-          @model.paragraphs << para
+          para = ParagraphBuilder.new(allocator: @allocator)
+          para << element
+          @model.paragraphs << para.build
         when Wordprocessingml::Run
-          # Auto-wrap Run in a paragraph, appending to the last one if possible
           if @model.paragraphs.empty?
-            para = Wordprocessingml::Paragraph.new
-            para.runs << element
-            @model.paragraphs << para
+            para = ParagraphBuilder.new(allocator: @allocator)
+            para << element
+            @model.paragraphs << para.build
           else
             @model.paragraphs.last.runs << element
           end
@@ -63,7 +63,7 @@ module Uniword
       # @yield [ParagraphBuilder] Builder for paragraph configuration
       # @return [ParagraphBuilder]
       def paragraph(text = nil, &block)
-        para = ParagraphBuilder.new
+        para = ParagraphBuilder.new(allocator: @allocator)
         para << text if text
         yield(para) if block
         @model.paragraphs << para.build

data/lib/uniword/builder/image_builder.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "securerandom"
+require "digest"
 require "stringio"
 
 module Uniword
@@ -27,20 +27,26 @@ module Uniword
       # Picture namespace URI for GraphicData
       PIC_URI = "http://schemas.openxmlformats.org/drawingml/2006/picture"
 
+      IMAGE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
+
       # Register an image part on the document for DOCX packaging.
       #
       # @param document [DocumentBuilder, DocumentRoot] Target document
       # @param path [String] Path to image file
-      # @return [String] Relationship ID (e.g., 'rIdImg1')
+      # @return [String] Relationship ID (e.g., 'rId5')
       def self.register_image(document, path)
         root = document.is_a?(Uniword::Builder::DocumentBuilder) ? document.model : document
-        if root
-          root.image_parts ||= {}
-          r_id = "rIdImg#{root.image_parts.size + 1}"
-        else
-          # No document context — generate a placeholder rId
-          r_id = "rIdImg#{SecureRandom.random_number(1_000_000)}"
-        end
+        alloc = document.is_a?(Uniword::Builder::DocumentBuilder) ? document.allocator : nil
+
+        target = "media/#{File.basename(path)}"
+        r_id = if alloc
+                 alloc.alloc_rid(target: target, type: IMAGE_REL_TYPE)
+               elsif root
+                 root.image_parts ||= {}
+                 "rId#{root.image_parts.size + 1}"
+               else
+                 "rId#{deterministic_id('img_rid', path)}"
+               end
 
         content_type = case File.extname(path).downcase
                        when ".png"  then "image/png"
@@ -53,6 +59,7 @@ module Uniword
                        end
 
         if root
+          root.image_parts ||= {}
           root.image_parts[r_id] = {
             path: path,
             data: File.binread(path),
@@ -133,11 +140,11 @@ alt_text: nil)
 
         drawing = Wordprocessingml::Drawing.new
 
-        inline = WpDrawing::Inline.new
+        inline = WpDrawing::Inline.new(dist_t: 0, dist_b: 0, dist_l: 0, dist_r: 0)
         inline.extent = WpDrawing::Extent.new(cx: w, cy: h)
-        inline.effect_extent = WpDrawing::EffectExtent.new
+        inline.effect_extent = WpDrawing::EffectExtent.new(l: 0, t: 0, r: 0, b: 0)
         inline.doc_properties = WpDrawing::DocProperties.new(
-          id: SecureRandom.random_number(1_000_000_000),
+          id: deterministic_id("inline", path),
           name: File.basename(path, ".*"),
         )
         inline.graphic = build_graphic(r_id, w, h)
@@ -217,7 +224,7 @@ alt_text: nil)
         end
 
         anchor.doc_properties = WpDrawing::DocProperties.new(
-          id: SecureRandom.random_number(1_000_000_000),
+          id: deterministic_id("anchor", path),
           name: File.basename(path, ".*"),
         )
         anchor.graphic = build_graphic(r_id, w, h)
@@ -266,7 +273,7 @@ alt_text: nil)
       end
 
       class << self
-        private
+        include DeterministicId
 
         # Build the Graphic > GraphicData > Picture chain
         #
@@ -295,8 +302,8 @@ alt_text: nil)
           # Non-visual properties
           pic.nv_pic_pr = Picture::NonVisualPictureProperties.new
           pic.nv_pic_pr.c_nv_pr = Drawingml::NonVisualDrawingProperties.new(
-            id: SecureRandom.random_number(1_000_000_000),
-            name: "Picture #{SecureRandom.random_number(1_000_000)}",
+            id: deterministic_id("pic", r_id),
+            name: "Picture",
           )
           pic.nv_pic_pr.c_nv_pic_pr = Picture::NonVisualPictureDrawingProperties.new
 
@@ -312,6 +319,7 @@ alt_text: nil)
           pic.sp_pr.xfrm.off = Drawingml::Offset.new(x: 0, y: 0)
           pic.sp_pr.xfrm.ext = Drawingml::Extents.new(cx: width, cy: height)
           pic.sp_pr.prst_geom = Drawingml::PresetGeometry.new(prst: "rect")
+          pic.sp_pr.prst_geom.av_lst = Drawingml::AdjustValueList.new
 
           pic
         end

data/lib/uniword/builder/list_builder.rb

@@ -40,7 +40,8 @@ module Uniword
       # @yield [ParagraphBuilder] Builder for item content
       # @return [ParagraphBuilder] The paragraph builder
       def item(text = nil, level: 0, &block)
-        para = ParagraphBuilder.new
+        alloc = @document.is_a?(DocumentBuilder) ? @document.allocator : nil
+        para = ParagraphBuilder.new(allocator: alloc)
         para.numbering(@num_id, level)
         para << text if text
         yield(para) if block

data/lib/uniword/builder/paragraph_builder.rb

@@ -1,31 +1,32 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Uniword
   module Builder
-    # Builds and configures Paragraph objects.
-    #
-    # Uses << operator to append child elements with smart type routing.
-    #
-    # @example Create a simple paragraph
-    #   para = ParagraphBuilder.new
-    #   para << 'Hello World'
-    #   para.build
-    #
-    # @example Styled paragraph with mixed content
-    #   para = ParagraphBuilder.new
-    #   para.style = 'Heading1'
-    #   para << Builder.text('Title', bold: true, size: 24)
-    #   para << Builder.hyperlink('https://example.com', 'link')
-    #   para << Builder.tab_stop(position: 7200)
-    #   para.build
     class ParagraphBuilder < BaseBuilder
       include HasBorders
       include HasShading
 
+      @sequence = 0
+      @mutex = Mutex.new
+
+      class << self
+        attr_accessor :sequence, :mutex
+      end
+
       def self.default_model_class
         Wordprocessingml::Paragraph
       end
 
+      attr_reader :allocator
+
+      def initialize(model = nil, allocator: nil)
+        @allocator = allocator
+        super(model)
+        assign_tracking_attributes
+      end
+
       # Append a child element. Routes by type:
       # - String -> creates a Run
       # - Run -> appends to runs
@@ -39,23 +40,36 @@ module Uniword
       def <<(element)
         case element
         when String
-          @model.runs << Wordprocessingml::Run.new(text: element)
+          append_string(element)
+        when Omml::Models::CTOMath, Omml::Models::OMath
+          @model.o_maths << element
+          track_element_order("oMath")
+        when Omml::Models::OMathPara
+          @model.o_math_paras << element
+          track_element_order("oMathPara")
         when Wordprocessingml::Run
-          @model.runs << element
+          append_run(element)
         when Wordprocessingml::Hyperlink
           @model.hyperlinks << element
+          track_element_order("hyperlink")
         when Properties::TabStop
           ensure_properties
           @model.properties.tabs ||= Properties::Tabs.new
           @model.properties.tabs << element
         when Wordprocessingml::BookmarkStart
           @model.bookmark_starts << element
+          track_element_order("bookmarkStart")
         when Wordprocessingml::BookmarkEnd
           @model.bookmark_ends << element
+          track_element_order("bookmarkEnd")
         when Wordprocessingml::StructuredDocumentTag
           @model.sdts << element
+          track_element_order("sdt")
+        when Wordprocessingml::SimpleField
+          @model.simple_fields << element
+          track_element_order("fldSimple")
         when RunBuilder
-          @model.runs << element.build
+          append_run(element.build)
         else
           raise ArgumentError, "Cannot add #{element.class} to paragraph"
         end
@@ -63,10 +77,14 @@ module Uniword
       end
 
       def style=(name)
-        ensure_properties.style = Properties::StyleReference.new(value: name)
+        ensure_properties.style = name
         self
       end
 
+      def style
+        @model.style
+      end
+
       def align=(value)
         ensure_properties.alignment = Properties::Alignment.new(value: value.to_s)
         self
@@ -146,8 +164,65 @@ module Uniword
 
       private
 
+      def assign_tracking_attributes
+        if @allocator
+          @model.rsid_r = @allocator.alloc_rsid
+          @model.para_id = Wordprocessingml::W14ParaId.new(@allocator.alloc_para_id)
+        else
+          idx = self.class.mutex.synchronize do
+            self.class.sequence += 1
+          end
+          hash = Digest::SHA256.hexdigest("para:#{idx}:#{Process.pid}")
+          @model.rsid_r = hash[0, 8]
+          @model.para_id = Wordprocessingml::W14ParaId.new(hash[8, 8])
+        end
+        @model.rsid_r_default = "00000000"
+        @model.text_id = Wordprocessingml::W14TextId.new("77777777")
+      end
+
+      def append_run(run)
+        return if RunUtils.empty_run?(run)
+
+        last = @model.runs.last
+        if last && RunUtils.mergeable?(last, run)
+          RunUtils.merge_text(last, run)
+        else
+          @model.runs << run
+          track_element_order("r")
+        end
+      end
+
+      def append_string(str)
+        return if str.nil? || str.empty?
+
+        unless str.include?("\n")
+          @model.runs << Wordprocessingml::Run.new(text: str)
+          track_element_order("r")
+          return
+        end
+
+        segments = str.split("\n", -1)
+        segments.each_with_index do |seg, i|
+          unless seg.empty?
+            @model.runs << Wordprocessingml::Run.new(text: seg)
+            track_element_order("r")
+          end
+          if i < segments.size - 1
+            br_run = Wordprocessingml::Run.new
+            br_run.break = Wordprocessingml::Break.new
+            @model.runs << br_run
+            track_element_order("r")
+          end
+        end
+      end
+
+      def properties_tag
+        "pPr"
+      end
+
       def ensure_properties
         @model.properties ||= Wordprocessingml::ParagraphProperties.new
+        ensure_properties_in_order
         @model.properties
       end
     end

data/lib/uniword/builder/run_utils.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Shared run utilities used by both ParagraphBuilder (build-time) and
+    # Reconciler::Helpers (reconcile-time).
+    #
+    # Provides canonical implementations of run classification and merging.
+    # Both modules delegate here to ensure identical behavior.
+    module RunUtils
+      module_function
+
+      # Whether a run contains no renderable content.
+      #
+      # A run is empty only if it has no text content and no structural
+      # elements (breaks, tabs, drawings, field chars, etc.).
+      def empty_run?(run)
+        return false if Array(run.break).any?
+        return false if run.tab
+        return false if run.drawings&.any?
+        return false if run.pictures&.any?
+        return false if run.alternate_content
+        return false if run.footnote_reference
+        return false if run.endnote_reference
+        return false if run.field_char
+        return false if run.instr_text
+        return false if run.position_tab
+        return false if run.del_text
+        return false if run.no_break_hyphen
+        return false if run.sym
+        return false if run.last_rendered_page_break
+        return false if run.separator_char
+        return false if run.continuation_separator_char
+
+        run.text_string.empty?
+      end
+
+      # Whether a run contains only text (no structural elements).
+      #
+      # Runs with drawings, breaks, tabs, field chars, etc. are NOT
+      # text-only and should never be merged with other runs.
+      def text_only_run?(run)
+        return false if run.drawings&.any?
+        return false if run.pictures&.any?
+        return false if run.alternate_content
+        return false if run.footnote_reference
+        return false if run.endnote_reference
+        return false if run.field_char
+        return false if run.instr_text
+        return false if run.sym
+        return false if Array(run.break).any?
+        return false if run.tab
+        return false if run.position_tab
+        return false if run.no_break_hyphen
+        return false if run.del_text
+
+        true
+      end
+
+      # Whether two runs have identical formatting (RunProperties).
+      def properties_match?(a, b)
+        rpr_a = a.properties
+        rpr_b = b.properties
+        return true if rpr_a.nil? && rpr_b.nil?
+        return false if rpr_a.nil? || rpr_b.nil?
+
+        rpr_a.to_xml == rpr_b.to_xml
+      end
+
+      # Whether two text-only runs can be merged.
+      #
+      # Runs can be merged if both are text-only with identical formatting.
+      def mergeable?(existing, incoming)
+        return false unless text_only_run?(existing) && text_only_run?(incoming)
+        return false if incoming.text_string.empty?
+
+        properties_match?(existing, incoming)
+      end
+
+      # Merge source run's text into target run.
+      #
+      # Handles xml:space="preserve" for whitespace-sensitive content.
+      def merge_text(target, source)
+        if Array(source.text).any?
+          existing = target.text_string
+          appended = source.text_string
+          combined = existing + appended
+          new_text = Wordprocessingml::Text.new(content: combined)
+          if Wordprocessingml::Text.preserve_whitespace?(combined)
+            new_text.xml_space = "preserve"
+          end
+          target.text = new_text
+        end
+      end
+    end
+  end
+end

data/lib/uniword/builder/section_builder.rb

@@ -21,18 +21,19 @@ module Uniword
         Wordprocessingml::SectionProperties
       end
 
+      def initialize(model = nil)
+        super
+        ensure_section_defaults
+      end
+
       def type=(value)
         @model.type = value
         self
       end
 
-      # Set page size
-      #
-      # @param width [Integer] Page width in twips (default US Letter: 12240)
-      # @param height [Integer] Page height in twips (default US Letter: 15840)
-      # @param orientation [String] 'portrait' or 'landscape'
-      # @return [self]
-      def page_size(width: 12_240, height: 15_840, orientation: "portrait")
+      def page_size(width: Wordprocessingml::PageDefaults::LETTER_WIDTH,
+                     height: Wordprocessingml::PageDefaults::LETTER_HEIGHT,
+                     orientation: "portrait")
         @model.page_size ||= Wordprocessingml::PageSize.new
         @model.page_size.width = width
         @model.page_size.height = height
@@ -40,16 +41,6 @@ module Uniword
         self
       end
 
-      # Set page margins
-      #
-      # @param top [Integer] Top margin in twips (default 1440 = 1 inch)
-      # @param bottom [Integer] Bottom margin in twips
-      # @param left [Integer] Left margin in twips
-      # @param right [Integer] Right margin in twips
-      # @param header [Integer] Header distance from edge in twips
-      # @param footer [Integer] Footer distance from edge in twips
-      # @param gutter [Integer] Gutter margin in twips
-      # @return [self]
       def margins(top: 1440, bottom: 1440, left: 1440, right: 1440,
                   header: 720, footer: 720, gutter: 0)
         @model.page_margins ||= Wordprocessingml::PageMargins.new
@@ -63,42 +54,6 @@ module Uniword
         self
       end
 
-      # Set number of columns
-      #
-      # @param count [Integer] Number of columns
-      # @param spacing [Integer] Space between columns in twips
-      # @return [self]
-      def columns(count: 1, spacing: 720)
-        @model.columns ||= Wordprocessingml::Columns.new
-        @model.columns.num = count
-        @model.columns.space = spacing
-        self
-      end
-
-      def page_borders(**_options)
-        @model.page_borders ||= Wordprocessingml::PageBorders.new
-        self
-      end
-
-      # Set line numbering
-      #
-      # @param count_by [Integer] Line numbering interval
-      # @param start [Integer] Starting line number
-      # @param restart [String] Restart setting ('continuous', 'newPage', 'newSection')
-      # @return [self]
-      def line_numbering(count_by: 1, start: 1, restart: "continuous")
-        @model.line_numbering ||= Wordprocessingml::LineNumbering.new
-        @model.line_numbering.count_by = count_by
-        @model.line_numbering.start = start
-        @model.line_numbering.restart = restart
-        self
-      end
-
-      # Set page numbering for this section
-      #
-      # @param start [Integer, nil] Starting page number
-      # @param format [String, nil] Number format ('decimal', 'lowerRoman', 'upperRoman')
-      # @return [self]
       def page_numbering(start: nil, format: nil)
         @model.page_numbering ||= Wordprocessingml::PageNumbering.new
         @model.page_numbering.start = start if start
@@ -106,37 +61,55 @@ module Uniword
         self
       end
 
-      # Configure a header for this section
-      #
-      # @param type [String] Header type ('default', 'first', 'even')
-      # @yield [HeaderFooterBuilder] Builder for header content
-      # @return [HeaderFooterBuilder] The header/footer builder
+      def columns(count: 1, spacing: 720)
+        @model.columns ||= Wordprocessingml::Columns.new
+        @model.columns.num = count
+        @model.columns.space = spacing
+        self
+      end
+
       def header(type: "default", &block)
         hf = HeaderFooterBuilder.new(:header, type: type)
-        yield(hf) if block
-
+        block&.call(hf)
         ref = Wordprocessingml::HeaderReference.new(
           type: type, r_id: "rIdHdr#{type}",
         )
         @model.header_references << ref
+        @header_builders ||= {}
+        @header_builders[type] = hf
         hf
       end
 
-      # Configure a footer for this section
-      #
-      # @param type [String] Footer type ('default', 'first', 'even')
-      # @yield [HeaderFooterBuilder] Builder for footer content
-      # @return [HeaderFooterBuilder] The header/footer builder
       def footer(type: "default", &block)
         hf = HeaderFooterBuilder.new(:footer, type: type)
-        yield(hf) if block
-
+        block&.call(hf)
         ref = Wordprocessingml::FooterReference.new(
           type: type, r_id: "rIdFtr#{type}",
         )
         @model.footer_references << ref
+        @footer_builders ||= {}
+        @footer_builders[type] = hf
         hf
       end
+
+      # Built header content models keyed by type.
+      def header_models
+        (@header_builders || {}).transform_values(&:build)
+      end
+
+      # Built footer content models keyed by type.
+      def footer_models
+        (@footer_builders || {}).transform_values(&:build)
+      end
+
+      private
+
+      def ensure_section_defaults
+        page_size
+        margins
+        columns
+        @model.doc_grid ||= Wordprocessingml::PageDefaults.default_doc_grid
+      end
     end
   end
 end