uniword 1.2.5 → 1.3.0

data/lib/uniword/wordprocessingml/page_setup.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Wordprocessingml
+    # Applies uniform page setup across every section of a document —
+    # Word's Layout dialog as an API.
+    #
+    # Paper size (named presets), orientation (with dimension swap, like
+    # Word), and margins (twips, or strings with in/cm/mm suffix).
+    # Header/footer/gutter margins are left untouched.
+    #
+    # @example A4 landscape with 2 cm margins
+    #   setup = PageSetup.new(size: "a4", orientation: "landscape",
+    #                         margins: "2cm")
+    #   setup.apply(document)
+    #   setup.sections_updated # => 1
+    class PageSetup
+      # Named paper sizes in twips [width, height] (portrait).
+      PAPER_SIZES = {
+        "letter" => [12_240, 15_840],
+        "legal" => [12_240, 20_160],
+        "a4" => [11_906, 16_838],
+        "a5" => [8_391, 11_906],
+        "executive" => [10_440, 15_120],
+      }.freeze
+
+      TWIPS_PER_INCH = 1440
+      TWIPS_PER_CM = 567
+      TWIPS_PER_MM = 57
+
+      ORIENTATIONS = %w[portrait landscape].freeze
+
+      # @return [Integer] number of sections updated
+      attr_reader :sections_updated
+
+      # @param size [String, nil] Paper size name (see PAPER_SIZES)
+      # @param orientation [String, nil] "portrait" or "landscape"
+      # @param margins [Integer, String, nil] Uniform margin for all four
+      #   sides (twips, or "1in" / "2.5cm" / "25mm")
+      # @param side_margins [Hash] Per-side overrides
+      #   (:top, :right, :bottom, :left)
+      # @raise [ArgumentError] on unknown size, orientation, or margin
+      def initialize(size: nil, orientation: nil, margins: nil,
+                     **side_margins)
+        @size = normalize_size(size)
+        @orientation = normalize_orientation(orientation)
+        @margins = side_margins.to_h do |side, value|
+          [side, parse_margin(value)]
+        end
+        uniform = parse_margin(margins)
+        %i[top right bottom left].each do |side|
+          @margins[side] = uniform if @margins[side].nil?
+        end
+        @sections_updated = 0
+      end
+
+      # Apply the setup to every section in the document.
+      #
+      # @param document [DocumentRoot] Document to update (mutated)
+      # @return [Integer] number of sections updated
+      def apply(document)
+        each_section_properties(document) do |sect_pr|
+          apply_page_size(sect_pr) if @size || @orientation
+          apply_margins(sect_pr)
+          @sections_updated += 1
+        end
+        sections_updated
+      end
+
+      private
+
+      def normalize_size(size)
+        return nil if size.nil?
+
+        dims = PAPER_SIZES[size.to_s.downcase]
+        unless dims
+          raise ArgumentError,
+                "Unknown paper size '#{size}'. " \
+                "Available: #{PAPER_SIZES.keys.join(', ')}"
+        end
+
+        dims
+      end
+
+      def normalize_orientation(orientation)
+        return nil if orientation.nil?
+
+        value = orientation.to_s.downcase
+        return value if ORIENTATIONS.include?(value)
+
+        raise ArgumentError,
+              "Unknown orientation '#{orientation}'. " \
+              "Available: #{ORIENTATIONS.join(', ')}"
+      end
+
+      # Parse a margin value: Integer (twips) or String with an
+      # in/cm/mm/dxa suffix (bare numbers are inches).
+      def parse_margin(value)
+        case value
+        when nil then nil
+        when Numeric then value.round
+        when /\A([\d.]+)\s*(in|cm|mm|dxa|twips?)?\z/i
+          amount = Regexp.last_match(1).to_f
+          unit = Regexp.last_match(2)&.downcase || "in"
+          to_twips(amount, unit)
+        else
+          raise ArgumentError, "Invalid margin '#{value}' " \
+                               "(use twips, or '1in' / '2.5cm' / '25mm')"
+        end
+      end
+
+      def to_twips(amount, unit)
+        factor = case unit
+                 when "in" then TWIPS_PER_INCH
+                 when "cm" then TWIPS_PER_CM
+                 when "mm" then TWIPS_PER_MM
+                 else 1
+                 end
+        (amount * factor).round
+      end
+
+      def each_section_properties(document, &block)
+        body = document.body
+        return unless body
+
+        yield body.section_properties if body.section_properties
+        each_paragraph_section(body, &block)
+      end
+
+      def each_paragraph_section(body)
+        (body.paragraphs || []).each do |paragraph|
+          sect_pr = paragraph.properties&.section_properties
+          yield sect_pr if sect_pr
+        end
+      end
+
+      def apply_page_size(sect_pr)
+        width, height = target_dimensions(sect_pr)
+
+        sect_pr.page_size ||= PageSize.new
+        sect_pr.page_size.width = width
+        sect_pr.page_size.height = height
+        sect_pr.page_size.orientation = @orientation if @orientation
+      end
+
+      def target_dimensions(sect_pr)
+        width, height = current_dimensions(sect_pr)
+        width, height = @size if @size
+        width, height = orient(width, height) if @orientation
+        [width, height]
+      end
+
+      def current_dimensions(sect_pr)
+        size = sect_pr.page_size
+        [size&.width || PageDefaults.default_page_size.width,
+         size&.height || PageDefaults.default_page_size.height]
+      end
+
+      # Word swaps width/height when flipping orientation.
+      def orient(width, height)
+        if (@orientation == "landscape" && width < height) ||
+            (@orientation == "portrait" && width > height)
+          [height, width]
+        else
+          [width, height]
+        end
+      end
+
+      def apply_margins(sect_pr)
+        return if @margins.values.all?(&:nil?)
+
+        sect_pr.page_margins ||= PageMargins.new
+        @margins.each do |side, value|
+          next if value.nil?
+
+          sect_pr.page_margins.method(:"#{side}=").call(value)
+        end
+      end
+    end
+  end
+end

data/lib/uniword/wordprocessingml/paragraph_properties.rb

@@ -116,7 +116,8 @@ module Uniword
             with: { from: :yaml_widow_control_from, to: :yaml_widow_control_to }
       end
 
-      # YAML transform methods (instance methods - called via send on an instance)
+      # YAML transform methods (instance methods called by lutaml-model's
+      # `with:` transform mechanism)
       def yaml_style_from(instance, value)
         if value
           instance.style = [
@@ -200,21 +201,6 @@ module Uniword
         # Style reference - maps w:pStyle w:val="..." to style attribute
         map_element "pStyle", to: :style, render_nil: false
 
-        # Alignment - maps w:jc w:val="..." to alignment attribute
-        map_element "jc", to: :alignment, render_nil: false
-
-        # Spacing (complex object - WORKS)
-        map_element "spacing", to: :spacing, render_nil: false
-
-        # Indentation (complex object)
-        map_element "ind", to: :indentation, render_nil: false
-
-        # Outline level (wrapper object)
-        map_element "outlineLvl", to: :outline_level, render_nil: false
-
-        # Numbering properties (wrapped in w:numPr)
-        map_element "numPr", to: :numbering_properties, render_nil: false
-
         # Keep options (only render if true)
         map_element "keepNext", to: :keep_next_wrapper, render_nil: false,
                                 render_default: false
@@ -225,32 +211,51 @@ module Uniword
         map_element "widowControl", to: :widow_control_wrapper, render_nil: false,
                                     render_default: false
 
-        # Spacing options (only render if true)
-        map_element "contextualSpacing", to: :contextual_spacing, render_nil: false,
-                                         render_default: false
+        # Numbering properties (wrapped in w:numPr)
+        map_element "numPr", to: :numbering_properties, render_nil: false
+
+        # Suppress line numbers (only render if true)
         map_element "suppressLineNumbers", to: :suppress_line_numbers, render_nil: false,
                                            render_default: false
 
-        # Bidirectional (only render if true)
-        map_element "bidi", to: :bidirectional, render_nil: false,
-                            render_default: false
+        # Borders (complex object)
+        map_element "pBdr", to: :borders, render_nil: false
+
+        # Shading (complex object)
+        map_element "shd", to: :shading, render_nil: false
+
+        # Tabs (complex object - collection)
+        map_element "tabs", to: :tabs, render_nil: false
 
         # East Asian typography
         map_element "autoSpaceDE", to: :auto_space_de, render_nil: false,
                                    render_default: false
         map_element "autoSpaceDN", to: :auto_space_dn, render_nil: false,
                                    render_default: false
+
+        # Bidirectional (only render if true)
+        map_element "bidi", to: :bidirectional, render_nil: false,
+                            render_default: false
+
+        # Right indent adjustment
         map_element "adjustRightInd", to: :adjust_right_ind, render_nil: false,
                                       render_default: false
 
-        # Borders (complex object)
-        map_element "pBdr", to: :borders, render_nil: false
+        # Spacing (complex object - WORKS)
+        map_element "spacing", to: :spacing, render_nil: false
 
-        # Tabs (complex object - collection)
-        map_element "tabs", to: :tabs, render_nil: false
+        # Indentation (complex object)
+        map_element "ind", to: :indentation, render_nil: false
 
-        # Shading (complex object)
-        map_element "shd", to: :shading, render_nil: false
+        # Contextual spacing (only render if true)
+        map_element "contextualSpacing", to: :contextual_spacing, render_nil: false,
+                                         render_default: false
+
+        # Alignment - maps w:jc w:val="..." to alignment attribute
+        map_element "jc", to: :alignment, render_nil: false
+
+        # Outline level (wrapper object)
+        map_element "outlineLvl", to: :outline_level, render_nil: false
 
         # Run properties (for pPr/rPr - style overrides)
         map_element "rPr", to: :run_properties, render_nil: false

data/lib/uniword/wordprocessingml/rsids.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
-require_relative "rsid_root"
-require_relative "rsid"
 
 module Uniword
   module Wordprocessingml

data/lib/uniword/wordprocessingml/run.rb

@@ -18,6 +18,7 @@ module Uniword
       attribute :alternate_content, AlternateContent, default: nil
       attribute :footnote_reference, FootnoteReference
       attribute :endnote_reference, EndnoteReference
+      attribute :comment_reference, CommentReference
       attribute :field_char, FieldChar
       attribute :instr_text, InstrText
       attribute :position_tab, PositionTab
@@ -55,6 +56,8 @@ module Uniword
                                          render_nil: false
         map_element "endnoteReference", to: :endnote_reference,
                                         render_nil: false
+        map_element "commentReference", to: :comment_reference,
+                                        render_nil: false
         map_element "fldChar", to: :field_char, render_nil: false
         map_element "instrText", to: :instr_text, render_nil: false
         map_element "ptab", to: :position_tab, render_nil: false

data/lib/uniword/wordprocessingml/section_properties.rb

@@ -50,14 +50,14 @@ module Uniword
 
         map_element "headerReference", to: :header_references, render_nil: false
         map_element "footerReference", to: :footer_references, render_nil: false
+        map_element "footnotePr", to: :footnote_pr, render_nil: false
         map_element "pgSz", to: :page_size, render_nil: false
         map_element "pgMar", to: :page_margins, render_nil: false
         map_attribute "val", to: :type
         map_element "pgNumType", to: :page_numbering, render_nil: false
         map_element "cols", to: :columns, render_nil: false
-        map_element "docGrid", to: :doc_grid, render_nil: false
-        map_element "footnotePr", to: :footnote_pr, render_nil: false
         map_element "titlePg", to: :title_pg, render_nil: false
+        map_element "docGrid", to: :doc_grid, render_nil: false
         map_element "footnoteColumns", to: :footnote_columns, render_nil: false
       end
     end

data/lib/uniword/wordprocessingml/settings.rb

@@ -2,34 +2,6 @@
 
 require "lutaml/model"
 require "nokogiri"
-require_relative "../properties/relationship_id"
-require_relative "zoom"
-require_relative "compat"
-require_relative "proof_state"
-require_relative "style_pane_format_filter"
-require_relative "default_tab_stop"
-require_relative "character_spacing_control"
-require_relative "do_not_display_page_boundaries"
-require_relative "rsids"
-require_relative "math_pr"
-require_relative "theme_font_lang"
-require_relative "clr_scheme_mapping"
-require_relative "shape_defaults"
-require_relative "decimal_symbol"
-require_relative "list_separator"
-require_relative "attached_template"
-require_relative "footnote_pr"
-require_relative "endnote_pr"
-require_relative "hdr_shape_defaults"
-require_relative "even_and_odd_headers"
-require_relative "mirror_margins"
-require_relative "do_not_include_subdocs_in_stats"
-require_relative "hyphenation_zone"
-require_relative "style_pane_sort_method"
-require_relative "doc_vars"
-require_relative "w14_doc_id"
-require_relative "w15_chart_tracking_ref_based"
-require_relative "w15_doc_id"
 
 module Uniword
   module Wordprocessingml
@@ -57,6 +29,7 @@ module Uniword
       attribute :footnote_pr, FootnotePr
       attribute :endnote_pr, EndnotePr
       attribute :hdr_shape_defaults, HdrShapeDefaults
+      attribute :update_fields, UpdateFields
       attribute :even_and_odd_headers, EvenAndOddHeaders
       attribute :mirror_margins, MirrorMargins
       attribute :do_not_include_subdocs_in_stats,
@@ -112,9 +85,9 @@ module Uniword
         map_element "doNotDisplayPageBoundaries",
                     to: :do_not_display_page_boundaries, render_nil: false
         map_element "mirrorMargins", to: :mirror_margins, render_nil: false
+        map_element "proofState", to: :proof_state, render_nil: false
         map_element "attachedTemplate", to: :attached_template,
                                         render_nil: false
-        map_element "proofState", to: :proof_state, render_nil: false
         map_element "stylePaneFormatFilter", to: :style_pane_format_filter,
                                              render_nil: false
         map_element "stylePaneSortMethod", to: :style_pane_sort_method,
@@ -126,6 +99,9 @@ module Uniword
                                          render_nil: false
         map_element "characterSpacingControl", to: :character_spacing_control,
                                                render_nil: false
+        map_element "updateFields", to: :update_fields, render_nil: false
+        map_element "hdrShapeDefaults", to: :hdr_shape_defaults,
+                                        render_nil: false
         map_element "footnotePr", to: :footnote_pr, render_nil: false
         map_element "endnotePr", to: :endnote_pr, render_nil: false
         map_element "compat", to: :compat, render_nil: false
@@ -137,11 +113,6 @@ module Uniword
                                         render_nil: false
         map_element "doNotIncludeSubdocsInStats",
                     to: :do_not_include_subdocs_in_stats, render_nil: false
-        map_element "hdrShapeDefaults", to: :hdr_shape_defaults,
-                                        render_nil: false
-        map_element "shapeDefaults", to: :shape_defaults, render_nil: false
-        map_element "decimalSymbol", to: :decimal_symbol, render_nil: false
-        map_element "listSeparator", to: :list_separator, render_nil: false
         # Both w14:docId and w15:docId use the same element name 'docId'
         # Separate map_element entries needed for namespace-aware matching
         # The namespace_scope ensures w14 and w15 namespaces are declared on root
@@ -150,6 +121,9 @@ module Uniword
         map_element "docId", to: :w14_doc_id, render_nil: false
         map_element "docId", to: :w15_doc_id, render_nil: false
         map_element "schemaLibrary", to: :schema_library, render_nil: false
+        map_element "shapeDefaults", to: :shape_defaults, render_nil: false
+        map_element "decimalSymbol", to: :decimal_symbol, render_nil: false
+        map_element "listSeparator", to: :list_separator, render_nil: false
       end
 
       # Override from_xml to manually deserialize w15:docId which has the same

data/lib/uniword/wordprocessingml/shape_defaults.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
-require_relative "../vml_office"
 
 module Uniword
   module Wordprocessingml

data/lib/uniword/wordprocessingml/style.rb

@@ -49,7 +49,8 @@ module Uniword
         map "run_properties", to: :rPr
       end
 
-      # YAML transform methods (instance methods - called via send on an instance)
+      # YAML transform methods (instance methods called by lutaml-model's
+      # `with:` transform mechanism)
       def yaml_name_from(instance, value)
         instance.name = StyleName.new(val: value) if value
       end

data/lib/uniword/wordprocessingml/style_cleanup.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Wordprocessingml
+    # Removes styles from a document's style definitions — Word's
+    # Styles-pane management as an API.
+    #
+    # `#remove_unused` deletes styles that no content references,
+    # directly (pStyle/rStyle/tblStyle in body, headers, footers, notes,
+    # comments) or transitively (basedOn/link/next chains from a used
+    # style, numbering level pStyle). Default styles (w:default="1")
+    # are never removed.
+    #
+    # @example Declutter a document
+    #   cleanup = StyleCleanup.new(document)
+    #   removed = cleanup.remove_unused # => ["ObsoleteStyle", ...]
+    class StyleCleanup
+      # @param document [DocumentRoot] Document to clean (mutated)
+      def initialize(document)
+        @document = document
+      end
+
+      # Remove one style by id (unless protected).
+      #
+      # @param style_id [String] Style id (w:styleId)
+      # @return [Boolean] true when the style was removed
+      def remove?(style_id)
+        return false if protected_id?(style_id)
+
+        before = styles.size
+        styles.delete_if { |style| style.styleId == style_id }
+        styles.size < before
+      end
+
+      # Ids of styles no content references.
+      #
+      # @return [Array<String>] Unreferenced, unprotected style ids
+      def unused_ids
+        used = used_ids
+        styles.filter_map(&:styleId).uniq - used - protected_ids
+      end
+
+      # Remove every unreferenced style.
+      #
+      # @return [Array<String>] Ids of removed styles
+      def remove_unused
+        ids = unused_ids
+        ids.each { |id| remove?(id) }
+        ids
+      end
+
+      private
+
+      def styles
+        @document.styles_configuration.styles
+      end
+
+      def protected_ids
+        styles.select(&:default).map(&:styleId)
+      end
+
+      def protected_id?(style_id)
+        protected_ids.include?(style_id)
+      end
+
+      # Ids referenced anywhere: content, notes, headers/footers,
+      # comments, numbering levels, and style-to-style chains.
+      def used_ids
+        used = content_style_ids + chain_seed_ids
+        expand_chains(used)
+      end
+
+      def content_style_ids
+        ids = []
+        walk_all_paragraphs do |paragraph|
+          ids.concat(paragraph_style_ids(paragraph))
+          ids.concat(run_style_ids(paragraph))
+        end
+        ids.concat(table_style_ids)
+        ids.concat(numbering_style_ids)
+        ids
+      end
+
+      # Styles referenced by other styles (basedOn/link/next) — chains
+      # are expanded from these too.
+      def chain_seed_ids
+        styles.flat_map { |style| chain_links(style) }
+      end
+
+      def chain_links(style)
+        [style.basedOn&.val, style.link&.val, style.nextStyle&.val].compact
+      end
+
+      def expand_chains(ids)
+        expanded = ids.to_set
+        loop do
+          additions = chain_additions(expanded)
+          break if additions.empty?
+
+          additions.each { |id| expanded << id }
+        end
+        expanded.to_a
+      end
+
+      def chain_additions(expanded)
+        styles.select { |style| expanded.include?(style.styleId) }
+          .flat_map { |style| chain_links(style) }
+          .reject { |id| expanded.include?(id) }
+      end
+
+      def paragraph_style_ids(paragraph)
+        Array(paragraph.properties&.style).filter_map(&:value)
+      end
+
+      def run_style_ids(paragraph)
+        paragraph_runs(paragraph)
+          .filter_map { |run| run.properties&.style&.value }
+      end
+
+      def paragraph_runs(paragraph)
+        (paragraph.runs || []) +
+          (paragraph.hyperlinks || []).flat_map(&:runs)
+      end
+
+      def table_style_ids
+        ids = []
+        walk_tables(@document.body) do |table|
+          ids << table.properties&.style&.val
+        end
+        ids.compact
+      end
+
+      def numbering_style_ids
+        numbering_definitions.flat_map do |definition|
+          (definition.levels || []).filter_map { |level| level.pStyle&.val }
+        end
+      end
+
+      def numbering_definitions
+        @document.numbering_configuration&.definitions || []
+      end
+
+      # Paragraphs in body (incl. table cells), headers/footers,
+      # notes, comments.
+      def walk_all_paragraphs(&block)
+        each_container { |container| walk_paragraphs(container, &block) }
+      end
+
+      def walk_paragraphs(container, &block)
+        return unless container
+
+        (container.paragraphs || []).each(&block)
+        walk_tables(container) { |table| walk_table_rows(table, &block) }
+      end
+
+      def walk_table_rows(table, &block)
+        (table.rows || []).each do |row|
+          (row.cells || []).each { |cell| walk_paragraphs(cell, &block) }
+        end
+      end
+
+      def walk_tables(container, &block)
+        return unless container
+
+        (container.tables || []).each do |table|
+          yield table
+          walk_table_cells(table, &block)
+        end
+      end
+
+      def walk_table_cells(table, &block)
+        (table.rows || []).each do |row|
+          (row.cells || []).each { |cell| walk_tables(cell, &block) }
+        end
+      end
+
+      def each_container(&block)
+        yield @document.body if @document.body
+        header_footer_containers.each(&block)
+        note_containers.each(&block)
+      end
+
+      def header_footer_containers
+        (@document.header_footer_parts || []).filter_map do |part|
+          part.content if part.content.is_a?(Lutaml::Model::Serializable)
+        end
+      end
+
+      def note_containers
+        [
+          @document.footnotes&.footnote_entries,
+          @document.endnotes&.endnote_entries,
+          @document.comments&.comments,
+        ].flatten.compact
+      end
+    end
+  end
+end

data/lib/uniword/wordprocessingml/table_cell_properties.rb

@@ -28,18 +28,18 @@ module Uniword
         namespace Uniword::Ooxml::Namespaces::WordProcessingML
         mixed_content
 
+        map_element "cnfStyle", to: :cnf_style, render_nil: false
         map_element "tcW", to: :cell_width, render_nil: false
-        map_element "tcBorders", to: :borders, render_nil: false
-        map_element "shd", to: :shading, render_nil: false
-        map_element "vAlign", to: :vertical_align, render_nil: false
         map_element "gridSpan", to: :grid_span, render_nil: false
         map_element "vMerge", to: :v_merge, render_nil: false
-        map_element "tcMar", to: :tc_mar, render_nil: false
-        map_element "cnfStyle", to: :cnf_style, render_nil: false
+        map_element "tcBorders", to: :borders, render_nil: false
+        map_element "shd", to: :shading, render_nil: false
         map_element "noWrap", to: :no_wrap, render_nil: false
-        map_element "hideMark", to: :hide_mark, render_nil: false
+        map_element "tcMar", to: :tc_mar, render_nil: false
         map_element "textDirection", to: :text_direction,
                                      render_nil: false
+        map_element "vAlign", to: :vertical_align, render_nil: false
+        map_element "hideMark", to: :hide_mark, render_nil: false
       end
     end
   end

data/lib/uniword/wordprocessingml/update_fields.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Uniword
+  module Wordprocessingml
+    # Update fields when the document is opened
+    #
+    # Element: <w:updateFields>
+    #
+    # When true, Word updates all fields (TOC, page numbers, cross
+    # references) the first time the document is opened — generated
+    # documents show correct field values without a manual F9.
+    class UpdateFields < Lutaml::Model::Serializable
+      attribute :value, Ooxml::Types::OoxmlBoolean,
+                default: -> { true }
+
+      xml do
+        element "updateFields"
+        namespace Uniword::Ooxml::Namespaces::WordProcessingML
+
+        map_attribute "val", to: :value, render_nil: false,
+                                        render_default: false
+      end
+    end
+  end
+end