uniword 1.7.1 → 1.7.3

data/lib/uniword/template/filler.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    # Fills document placeholders (mail merge) from a data hash.
+    #
+    # Three placeholder sources are recognised, in precedence order:
+    #
+    # 1. Content controls — a w:sdt whose sdtPr alias or tag names a
+    #    variable has its content replaced with the value (the first
+    #    run's properties are kept, extra runs are dropped).
+    # 2. Mail merge fields — a w:fldSimple whose instr is
+    #    `MERGEFIELD name` (first token after MERGEFIELD, quoted names
+    #    allowed) has its run content replaced with the value.
+    # 3. `{{var}}` text placeholders inside run text (w:t).
+    #
+    # Data keys may be strings or symbols; nested hashes are flattened
+    # to dotted paths ({"client" => {"name" => "X"}} fills
+    # {{client.name}}).
+    #
+    # V1 limitations:
+    # - A `{{var}}` placeholder must be fully contained in a single
+    #   run's text; cross-run placeholders are not stitched.
+    # - Only the main document body is scanned (paragraphs, tables,
+    #   block/inline content controls, hyperlink runs); headers,
+    #   footers, footnotes, and complex (fldChar) fields are not.
+    # - A filled content control's value is inserted verbatim and is
+    #   not rescanned for further placeholders.
+    #
+    # @example
+    #   result = Filler.new(document).fill(
+    #     { "client" => { "name" => "X" }, "total" => 42 }
+    #   )
+    #   result.total_filled  # => 2
+    #   result.missing       # => ["editor"]
+    class Filler
+      PLACEHOLDER_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/
+      MERGEFIELD_PATTERN = /\A\s*MERGEFIELD\s+(?:"([^"]*)"|(\S+))/i
+
+      # @param document [Wordprocessingml::DocumentRoot] document to fill
+      def initialize(document)
+        @document = document
+      end
+
+      # Fill all recognised placeholders in the document body.
+      #
+      # @param data [Hash] values keyed by variable name (nested hashes
+      #   become dotted paths); missing keys leave their placeholders
+      #   untouched
+      # @param strict [Boolean] when true, raise MissingVariablesError
+      #   if any placeholder names a variable absent from +data+
+      # @return [FillResult] filled counts per source kind and missing names
+      # @raise [MissingVariablesError] when strict and variables are missing
+      def fill(data, strict: false)
+        @variables = flatten_data(data)
+        @result = FillResult.new
+
+        fill_container(@document.body) if @document.body
+
+        if strict && @result.missing.any?
+          raise MissingVariablesError, @result.missing
+        end
+
+        @result
+      end
+
+      private
+
+      # Recursively fill one block-level container. Dispatch is
+      # explicit per container class (mirrors FindReplace::ParagraphWalker):
+      # Body maps structured_document_tags, TableCell maps no SDTs, and
+      # SDT Content maps sdts plus direct runs.
+      def fill_container(container)
+        case container
+        when Wordprocessingml::Body
+          fill_body(container)
+        when Wordprocessingml::TableCell
+          fill_cell(container)
+        when Wordprocessingml::StructuredDocumentTag::Content
+          fill_sdt_content(container)
+        end
+      end
+
+      def fill_body(body)
+        Array(body.structured_document_tags).each { |sdt| fill_sdt(sdt) }
+        fill_paragraphs(body.paragraphs)
+        fill_tables(body.tables)
+      end
+
+      def fill_cell(cell)
+        fill_paragraphs(cell.paragraphs)
+        fill_tables(cell.tables)
+      end
+
+      def fill_sdt_content(content)
+        Array(content.sdts).each { |sdt| fill_sdt(sdt) }
+        fill_paragraphs(content.paragraphs)
+        fill_tables(content.tables)
+        fill_run_placeholders(Array(content.runs))
+      end
+
+      def fill_tables(tables)
+        Array(tables).each do |table|
+          Array(table.rows).each do |row|
+            Array(row.cells).each { |cell| fill_container(cell) if cell }
+          end
+        end
+      end
+
+      def fill_paragraphs(paragraphs)
+        Array(paragraphs).each { |para| fill_paragraph(para) }
+      end
+
+      def fill_paragraph(para)
+        fill_run_placeholders(Array(para.runs))
+        Array(para.sdts).each { |sdt| fill_sdt(sdt) }
+        Array(para.simple_fields).each { |field| fill_field(field) }
+        fill_hyperlink_placeholders(para)
+      end
+
+      def fill_hyperlink_placeholders(para)
+        Array(para.hyperlinks).each do |link|
+          fill_run_placeholders(Array(link.runs))
+        end
+      end
+
+      # Content control: alias wins over tag as the variable name.
+      def fill_sdt(sdt)
+        name = sdt_variable_name(sdt)
+
+        if name
+          if @variables.key?(name)
+            write_value(sdt_run_slots(sdt), stringify(@variables[name]),
+                        sdt_append_target(sdt))
+            @result.add(:sdt)
+            return
+          end
+
+          @result.record_missing(name)
+        end
+
+        fill_container(sdt.content) if sdt.content
+      end
+
+      # Simple field: parse the MERGEFIELD instruction, fill when known.
+      def fill_field(field)
+        name = parse_mergefield(field.instr)
+        return unless name
+
+        if @variables.key?(name)
+          slots = Array(field.runs).map { |run| [field.runs, run] }
+          write_value(slots, stringify(@variables[name]), field.runs)
+          @result.add(:mergefield)
+        else
+          @result.record_missing(name)
+        end
+      end
+
+      # {{var}} substitution inside each run's text elements.
+      def fill_run_placeholders(runs)
+        runs.each do |run|
+          Array(run.text).each { |text_el| fill_text_object(text_el) }
+        end
+      end
+
+      def fill_text_object(text_el)
+        content = text_el.content.to_s
+        replaced = replace_placeholders(content)
+        return if replaced == content
+
+        text_el.content = replaced
+        preserve = Wordprocessingml::Text.preserve_whitespace?(replaced)
+        text_el.xml_space = preserve ? "preserve" : nil
+      end
+
+      # Substitute every {{var}} occurrence, recording missing names
+      # and leaving those placeholders verbatim.
+      def replace_placeholders(content)
+        content.gsub(PLACEHOLDER_PATTERN) do
+          match = Regexp.last_match
+          name = match[1]
+
+          if @variables.key?(name)
+            @result.add(:text)
+            stringify(@variables[name])
+          else
+            @result.record_missing(name)
+            match[0]
+          end
+        end
+      end
+
+      # Run slots ([collection, run] pairs) inside a content control,
+      # in document order: direct content runs, then paragraph runs
+      # (including runs inside paragraph hyperlinks).
+      def sdt_run_slots(sdt)
+        content = sdt.content
+        return [] if content.nil?
+
+        slots = run_slots(content.runs)
+        Array(content.paragraphs).each do |para|
+          slots.concat(para_run_slots(para))
+        end
+        slots
+      end
+
+      def run_slots(runs)
+        Array(runs).map { |run| [runs, run] }
+      end
+
+      def para_run_slots(para)
+        slots = run_slots(para.runs)
+        Array(para.hyperlinks).each do |link|
+          slots.concat(run_slots(link.runs))
+        end
+        slots
+      end
+
+      # Where a fresh run is appended when a content control has no
+      # runs at all: the first content paragraph, else the content's
+      # direct run collection.
+      def sdt_append_target(sdt)
+        content = sdt.content
+        return nil if content.nil?
+
+        first_para = Array(content.paragraphs).first
+        first_para ? first_para.runs : content.runs
+      end
+
+      # Write a value into run slots: keep the first run (and its
+      # properties) with the new text, drop the remaining runs. When
+      # there are no runs, append a fresh run unless the value is
+      # empty.
+      def write_value(slots, value, append_target)
+        if slots.empty?
+          return if value.empty? || append_target.nil?
+
+          append_target << Wordprocessingml::Run.new(text: [make_text(value)])
+          return
+        end
+
+        _owner, first = slots.first
+        first.text = [make_text(value)]
+        slots.drop(1).each { |owner, run| owner.delete(run) }
+      end
+
+      def sdt_variable_name(sdt)
+        props = sdt.properties
+        return nil unless props
+
+        alias_name = props.alias_name&.value.to_s
+        return alias_name unless alias_name.empty?
+
+        tag = props.tag&.value.to_s
+        tag.empty? ? nil : tag
+      end
+
+      def parse_mergefield(instr)
+        match = instr.to_s.match(MERGEFIELD_PATTERN)
+        return nil unless match
+
+        match[1] || match[2]
+      end
+
+      # Text object following the run text convention: xml:space
+      # preserved when the value has leading/trailing spaces, tabs, or
+      # newlines (mirrors Run's own text handling).
+      def make_text(string)
+        text_el = Wordprocessingml::Text.new(content: string)
+        text_el.xml_space = "preserve" if Wordprocessingml::Text.preserve_whitespace?(string)
+        text_el
+      end
+
+      def stringify(value)
+        value.nil? ? "" : value.to_s
+      end
+
+      # Flatten nested hashes into dotted-path string keys.
+      def flatten_data(hash, prefix = nil)
+        hash.each_with_object({}) do |(key, value), out|
+          name = prefix ? "#{prefix}.#{key}" : key.to_s
+
+          if value.is_a?(Hash)
+            out.update(flatten_data(value, name))
+          else
+            out[name] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/template.rb

@@ -9,6 +9,8 @@ module Uniword
     autoload :TemplateValidator, "#{__dir__}/template/template_validator"
     autoload :TemplateContext, "#{__dir__}/template/template_context"
     autoload :TemplateMarker, "#{__dir__}/template/template_marker"
+    autoload :Filler, "#{__dir__}/template/filler"
+    autoload :FillResult, "#{__dir__}/template/fill_result"
     autoload :Helpers, "#{__dir__}/template/helpers"
   end
 end

data/lib/uniword/transformation/mhtml_element_renderer.rb

@@ -211,7 +211,13 @@ module Uniword
         style_attrs << "height:#{height_px}px" if height_px
         style = style_attrs.empty? ? "" : " style='#{style_attrs.join(';')}'"
 
-        %(<img src="#{image_target}"#{style}>)
+        # No alt attribute at all when the drawing carries no description.
+        # An empty alt says "decorative", which is a claim about the image
+        # we have no grounds to make.
+        alt_text = drawing.alt_text
+        alt = alt_text ? %( alt="#{escape_xml(alt_text)}") : ""
+
+        %(<img src="#{image_target}"#{alt}#{style}>)
       end
 
       # Resolve image target path from image_parts
@@ -636,9 +642,9 @@ module Uniword
 
         attrs << %(w:id="#{props.id.value}") if props.id&.value
 
-        attrs << 'w:showingPlcHdr="t"' if props.showing_placeholder_header
+        attrs << 'w:showingPlcHdr="t"' if props.showing_placeholder_header&.on?
 
-        attrs << 'w:temporary="t"' if props.temporary
+        attrs << 'w:temporary="t"' if props.temporary&.on?
 
         if props.placeholder&.doc_part
           doc_part = props.placeholder.doc_part

data/lib/uniword/transformation/ooxml_to_html_converter.rb

@@ -60,9 +60,14 @@ module Uniword
         props = run.properties
         return text unless props
 
-        # Apply inline formatting
-        text = "<strong>#{text}</strong>" if props.bold
-        text = "<em>#{text}</em>" if props.italic
+        # Apply inline formatting.
+        #
+        # w:b and w:i are ST_OnOff toggles, so they are read through
+        # BooleanElement#on? and an explicit off ("0"/"false"/"off") stays
+        # off. The reads below are value elements, not toggles: w:u carries
+        # an ST_Underline style, the rest carry plain values.
+        text = "<strong>#{text}</strong>" if props.bold&.on?
+        text = "<em>#{text}</em>" if props.italic&.on?
         text = "<u>#{text}</u>" if props.underline&.value
         text = "<span style=\"color:#{props.color&.value}\">#{text}</span>" if props.color&.value
         text = "<span style=\"font-size:#{font_size_to_html(props.size&.value)}\">#{text}</span>" if props.size&.value

data/lib/uniword/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Uniword
-  VERSION = "1.7.1"
+  VERSION = "1.7.3"
 end

data/lib/uniword/wordprocessingml/deleted_paragraph_mark.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Uniword
+  module Wordprocessingml
+    # Deleted paragraph mark
+    #
+    # Element: <w:del> (CT_TrackChange) as it appears inside
+    # <w:pPr>/<w:rPr>: the paragraph mark itself was deleted while
+    # tracking changes, so accepting the revision merges the paragraph
+    # with the following one. Carries only the revision identity; the
+    # deleted text lives in sibling <w:del> run wrappers.
+    #
+    # @example
+    #   mark = DeletedParagraphMark.new(id: "9", author: "Alice")
+    class DeletedParagraphMark < Lutaml::Model::Serializable
+      attribute :id, Ooxml::Types::WmlVal
+      attribute :author, Ooxml::Types::WmlVal
+      attribute :date, Ooxml::Types::WmlVal
+
+      xml do
+        element "del"
+        namespace Uniword::Ooxml::Namespaces::WordProcessingML
+
+        map_attribute "id", to: :id, render_nil: false
+        map_attribute "author", to: :author, render_nil: false
+        map_attribute "date", to: :date, render_nil: false
+      end
+    end
+  end
+end

data/lib/uniword/wordprocessingml/document_root.rb

@@ -292,16 +292,31 @@ module Uniword
         body&.tables || []
       end
 
+      # Every paragraph in the document, including the ones inside table
+      # cells and inside tables nested in those cells.
+      #
+      # Top-level paragraphs come first, then table paragraphs: w:p and w:tbl
+      # are separate collections on the model, so their interleaving is not
+      # recoverable here.
+      #
+      # @return [Array<Paragraph>] All paragraphs, top-level ones first
+      def all_paragraphs
+        return [] unless body
+
+        (body.paragraphs || []) +
+          (body.tables || []).flat_map { |table| table_paragraphs(table) }
+      end
+
       # Get all drawings (image references) from the document.
-      # Walks all paragraphs and collects Drawing elements from runs.
+      # Walks every paragraph, table cells included, and collects Drawing
+      # elements from runs. A drawing in a table cell is still an image the
+      # renderer emits, so the accessibility and quality rules must see it.
       #
       # @return [Array<Drawing>] All drawing elements in document
       def images
-        return [] unless body&.paragraphs
-
-        body.paragraphs.flat_map do |para|
-          (para.runs || []).flat_map(&:drawings)
-        end.compact
+        all_paragraphs
+          .flat_map { |para| (para.runs || []).flat_map(&:drawings) }
+          .compact
       end
 
       # @return [Hash] Document statistics (paragraphs, tables, images)
@@ -369,6 +384,25 @@ module Uniword
 
       private
 
+      # Paragraphs held by a table, walking nested tables as well.
+      #
+      # @param table [Table] Table to walk
+      # @return [Array<Paragraph>] Paragraphs in that table
+      def table_paragraphs(table)
+        cells = (table.rows || []).flat_map { |row| row.cells || [] }
+        cells.flat_map { |cell| cell_paragraphs(cell) }
+      end
+
+      # Paragraphs held by one table cell, including its nested tables.
+      #
+      # @param cell [TableCell] Cell to walk
+      # @return [Array<Paragraph>] Paragraphs in that cell
+      def cell_paragraphs(cell)
+        nested = (cell.tables || [])
+          .flat_map { |table| table_paragraphs(table) }
+        (cell.paragraphs || []) + nested
+      end
+
       # Run model-level validation rules against this document.
       #
       # @return [Array<Validation::Report::ValidationIssue>] issues found

data/lib/uniword/wordprocessingml/drawing.rb

@@ -19,6 +19,57 @@ module Uniword
         map_element "inline", to: :inline, render_nil: false
         map_element "anchor", to: :anchor, render_nil: false
       end
+
+      # Alternative text for the drawing.
+      #
+      # Alt text lives in the descr attribute of wp:docPr. ECMA-376 names
+      # descr the description of the object; title is the object's caption,
+      # which Word's modern Alt Text pane does not write and screen readers
+      # do not announce. Word documents in the ISO corpus carry their alt
+      # text in descr with no title at all, so title is deliberately not a
+      # fallback here — see #alt_title.
+      #
+      # CT_Drawing is a choice over wp:inline and wp:anchor, so a drawing may
+      # carry either or both. Take the first frame supplying a non-blank
+      # description. Surrounding whitespace is not description, so the value
+      # is stripped and a blank one counts as absent.
+      #
+      # @return [String, nil] Alternative text, or nil when absent
+      def alt_text
+        first_non_blank(:descr)
+      end
+
+      # Set the alternative text on whichever frame this drawing carries.
+      # A drawing with neither frame has nowhere to put it.
+      #
+      # @param text [String, nil] Alternative text
+      def alt_text=(text)
+        frame = inline || anchor
+        unless frame.nil?
+          frame.doc_properties ||= WpDrawing::DocProperties.new
+          frame.doc_properties.descr = text
+        end
+      end
+
+      # The drawing's title (Word's legacy "Title" field), which is a caption
+      # rather than a text alternative. Reported so a rule can tell an author
+      # that their description is sitting in the wrong field.
+      #
+      # @return [String, nil] Title, or nil when absent
+      def alt_title
+        first_non_blank(:title)
+      end
+
+      private
+
+      # @param attribute [Symbol] docPr attribute to read
+      # @return [String, nil] First non-blank value across the frames
+      def first_non_blank(attribute)
+        [inline, anchor]
+          .filter_map { |frame| frame&.doc_properties&.public_send(attribute) }
+          .map(&:strip)
+          .find { |text| !text.empty? }
+      end
     end
   end
 end

data/lib/uniword/wordprocessingml/inserted_paragraph_mark.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Uniword
+  module Wordprocessingml
+    # Inserted paragraph mark
+    #
+    # Element: <w:ins> (CT_TrackChange) as it appears inside
+    # <w:pPr>/<w:rPr>: the paragraph mark itself was inserted while
+    # tracking changes, so the whole paragraph reads as a tracked
+    # insertion and rejecting the revision removes the paragraph.
+    # Carries only the revision identity.
+    #
+    # @example
+    #   mark = InsertedParagraphMark.new(id: "10", author: "Alice")
+    class InsertedParagraphMark < Lutaml::Model::Serializable
+      attribute :id, Ooxml::Types::WmlVal
+      attribute :author, Ooxml::Types::WmlVal
+      attribute :date, Ooxml::Types::WmlVal
+
+      xml do
+        element "ins"
+        namespace Uniword::Ooxml::Namespaces::WordProcessingML
+
+        map_attribute "id", to: :id, render_nil: false
+        map_attribute "author", to: :author, render_nil: false
+        map_attribute "date", to: :date, render_nil: false
+      end
+    end
+  end
+end