uniword 1.2.5 → 1.3.0

data/lib/uniword/wordprocessingml/document_root.rb

@@ -94,28 +94,17 @@ module Uniword
       # Additional attributes for DOCX metadata (not part of document.xml)
       # These are stored in separate files within the DOCX package
       attr_accessor :theme, :raw_html, :revisions, :comments
-      # Headers and footers (stored as hash: type => Header/Footer)
-      # Single-section only. For multi-section, use header_footer_parts.
-      attr_accessor :headers, :footers
-      # Multi-section headers/footers (ordered array):
-      # [{r_id: "rIdH1", target: "header1.xml", rel_type: "...",
-      #   content_type: "...", content: Header|Footer}]
-      attr_accessor :header_footer_parts
       # Footnotes and endnotes (separate XML parts in DOCX package)
       attr_accessor :footnotes, :endnotes
       # Image parts to embed in the DOCX package
       # Hash: r_id => { path: String, data: String, content_type: String, target: String }
       attr_accessor :image_parts
-      # Chart parts to embed in the DOCX package
-      # Hash: r_id => { xml: String, target: String }
-      attr_accessor :chart_parts
       # Bibliography sources for sources.xml
       attr_accessor :bibliography_sources
-      # OLE/embedded object binaries (word/embeddings/*)
-      attr_accessor :embeddings
       # Round-trip parts (copied from DocxPackage during load)
       attr_accessor :settings, :font_table, :web_settings, :document_rels, :theme_rels,
-                    :package_rels, :content_types, :custom_properties, :custom_xml_items
+                    :package_rels, :content_types, :custom_properties, :custom_xml_items,
+                    :settings_rels, :footnotes_rels, :endnotes_rels
       # Central ID allocator — preserves IDs across build/save cycle
       attr_accessor :allocator
 
@@ -123,6 +112,72 @@ module Uniword
       # (removing from attr_accessor to avoid shadowing custom getters)
       attr_writer :app_properties, :core_properties, :bookmarks
 
+      # Unified header/footer part store — the single storage path
+      # for both round-tripped and builder-created headers/footers.
+      #
+      # @return [Docx::HeaderFooterPartCollection] ordered part store
+      def header_footer_parts
+        @header_footer_parts ||= Docx::HeaderFooterPartCollection.new
+      end
+
+      # Replace the whole store (accepts HeaderFooterPart objects and
+      # legacy part hashes).
+      def header_footer_parts=(parts)
+        header_footer_parts.replace_all(parts)
+      end
+
+      # Headers view over the unified store (Hash-style by sectPr
+      # type, Array-style over parts).
+      #
+      # @return [Docx::HeaderFooterView]
+      def headers
+        @headers ||=
+          Docx::HeaderFooterView.new(header_footer_parts, :header)
+      end
+
+      # Bulk-assign headers (nil clears; Hash of type => model; Array
+      # of models/parts).
+      def headers=(value)
+        headers.replace(value)
+      end
+
+      # Footers view over the unified store.
+      #
+      # @return [Docx::HeaderFooterView]
+      def footers
+        @footers ||=
+          Docx::HeaderFooterView.new(header_footer_parts, :footer)
+      end
+
+      # Bulk-assign footers (see #headers=).
+      def footers=(value)
+        footers.replace(value)
+      end
+
+      # Chart parts to embed in the DOCX package, keyed by rId.
+      #
+      # @return [Docx::PartCollection] rId => ChartPart
+      def chart_parts
+        @chart_parts ||= Docx::PartCollection.new(:r_id, Docx::ChartPart)
+      end
+
+      # Bulk-assign chart parts (Hash of rId => ChartPart/hash; nil clears).
+      def chart_parts=(value)
+        chart_parts.replace_all(value)
+      end
+
+      # OLE/embedded object binaries (word/embeddings/*), keyed by target.
+      #
+      # @return [Docx::PartCollection] target => Part
+      def embeddings
+        @embeddings ||= Docx::PartCollection.new(:target, Docx::Part)
+      end
+
+      # Bulk-assign embeddings (Hash of target => Part/binary; nil clears).
+      def embeddings=(value)
+        embeddings.replace_all(value)
+      end
+
       # Get app_properties (lazy initialization)
       #
       # @return [Uniword::Ooxml::AppProperties] The app properties object
@@ -168,17 +223,24 @@ module Uniword
       #
       # @param path [String] Output file path
       # @param format [Symbol] Format (:docx, :mhtml, :auto)
-      def save(path, format: :auto, profile: nil)
+      # @param profile [Docx::Profile, nil] Profile for reconciliation
+      # @param validate [Boolean, nil] Run the package integrity gate before
+      #   writing; nil falls back to Uniword.configuration.validate_on_save
+      # @return [void]
+      def save(path, format: :auto, profile: nil, validate: nil)
         writer = DocumentWriter.new(self)
-        writer.save(path, format: format, profile: profile)
+        writer.save(path, format: format, profile: profile, validate: validate)
       end
 
       # Save document to DOCX file using DocxPackage
       #
       # @param path [String] Output file path
       # @param profile [Docx::Profile, nil] Profile for reconciliation
-      def to_file(path, profile: nil)
-        Docx::Package.to_file(self, path, profile: profile)
+      # @param validate [Boolean, nil] Run the package integrity gate before
+      #   writing; nil falls back to Uniword.configuration.validate_on_save
+      # @return [void]
+      def to_file(path, profile: nil, validate: nil)
+        Docx::Package.to_file(self, path, profile: profile, validate: validate)
       end
 
       # Get all paragraph text
@@ -226,26 +288,26 @@ module Uniword
       end
 
       # Check if document structure is valid.
-      # Runs structural checks via Validation::StructuralValidator.
+      # Runs model-level validation rules via Validation::Engine.
       # Use the verify CLI command for full OPC + XSD + semantic validation.
       #
       # @return [Boolean] true if document has valid structure
       def valid?
-        Validation::StructuralValidator.new(self).valid?
+        validation_errors.empty?
       end
 
       # Get structural validation errors.
       #
       # @return [Array<String>] Error messages
       def validation_errors
-        Validation::StructuralValidator.new(self).errors
+        structural_issues.select(&:error?).map(&:message)
       end
 
       # Get structural validation warnings.
       #
       # @return [Array<String>] Warning messages
       def validation_warnings
-        Validation::StructuralValidator.new(self).warnings
+        structural_issues.reject(&:error?).map(&:message)
       end
 
       # Get bookmarks from document paragraphs
@@ -314,6 +376,113 @@ module Uniword
         self
       end
 
+      # Apply a bundled font scheme to the document's theme
+      #
+      # Mirrors Word's Design → Fonts gallery: replaces only the theme's
+      # fontScheme — colors and formats are untouched. Creates the theme
+      # part from the bundled Office theme when the document has none.
+      #
+      # @param name [String, Symbol] Font scheme slug (data/font_schemes/)
+      # @return [self] For method chaining
+      # @raise [ArgumentError] if the scheme is unknown
+      def apply_font_scheme(name)
+        fonts = Resource::FontSchemeLoader.load(name.to_s)
+        transformation = Themes::ThemeTransformation.new
+        ensure_theme!(transformation)
+        theme.theme_elements.font_scheme =
+          transformation.build_font_scheme(fonts)
+        self
+      end
+
+      # Apply a bundled color scheme to the document's theme
+      #
+      # Mirrors Word's Design → Colors gallery: replaces only the theme's
+      # clrScheme — fonts and formats are untouched. Creates the theme
+      # part from the bundled Office theme when the document has none.
+      #
+      # @param name [String, Symbol] Color scheme slug (data/color_schemes/)
+      # @return [self] For method chaining
+      # @raise [ArgumentError] if the scheme is unknown
+      def apply_color_scheme(name)
+        colors = Resource::ColorSchemeLoader.load(name.to_s)
+        transformation = Themes::ThemeTransformation.new
+        ensure_theme!(transformation)
+        theme.theme_elements.clr_scheme =
+          transformation.build_color_scheme(colors)
+        self
+      end
+
+      # Replace one font family with another across the document
+      #
+      # Mirrors Word's Home → Replace → Replace Fonts: rewrites rFonts
+      # references in styles and defaults, body content, headers,
+      # footers, notes, comments, and numbering. Theme font references
+      # (asciiTheme etc.) are untouched — use #apply_font_scheme for
+      # those.
+      #
+      # @param from [String] Font family to replace (exact match)
+      # @param to [String] Replacement font family
+      # @return [Integer] Number of rFonts attribute values rewritten
+      def replace_font(from:, to:)
+        replacer = FontReplacer.new(from: from, to: to)
+        replacer.replace(self)
+      end
+
+      # Apply uniform page setup to every section of the document
+      #
+      # Mirrors Word's Layout dialog: named paper sizes, orientation
+      # (with Word-style dimension swap), and margins.
+      #
+      # @param size [String, nil] Paper size: letter, legal, a4, a5,
+      #   executive
+      # @param orientation [String, nil] "portrait" or "landscape"
+      # @param margins [Integer, String, nil] Uniform margin for all
+      #   sides (twips, or "1in" / "2.5cm" / "25mm")
+      # @param top, right, bottom, left [Integer, String, nil] Per-side
+      #   margin overrides
+      # @return [Integer] Number of sections updated
+      def apply_page_setup(size: nil, orientation: nil, margins: nil,
+                           top: nil, right: nil, bottom: nil, left: nil)
+        setup = PageSetup.new(size: size, orientation: orientation,
+                              margins: margins, top: top, right: right,
+                              bottom: bottom, left: left)
+        setup.apply(self)
+      end
+
+      # Remove one style from the document's style definitions
+      #
+      # Default styles (w:default="1") are never removed.
+      #
+      # @param style_id [String] Style id (w:styleId)
+      # @return [Boolean] true when the style was removed
+      def remove_style(style_id)
+        StyleCleanup.new(self).remove?(style_id)
+      end
+
+      # Rename a style's display name (w:name) — Word's style rename.
+      # References (pStyle/rStyle/tblStyle) target the styleId, so they
+      # keep working unchanged.
+      #
+      # @param identifier [String] Style id (w:styleId) or current
+      #   display name (w:name)
+      # @param new_name [String] New display name
+      # @return [Style, nil] The renamed style, or nil when not found
+      def rename_style(identifier, new_name)
+        style = styles_configuration.style(identifier)
+        return unless style
+
+        style.name = StyleName.new(val: new_name)
+        style
+      end
+
+      # Remove every style that no content references — Word's
+      # Styles-pane decluttering as one call. Default styles are kept.
+      #
+      # @return [Array<String>] Ids of removed styles
+      def remove_unused_styles
+        StyleCleanup.new(self).remove_unused
+      end
+
       # Auto-transition from MS theme to Uniword equivalent
       #
       # Detects the MS theme in the document's embedded theme and replaces
@@ -376,6 +545,27 @@ module Uniword
       def to_html_document
         Uniword::Transformation::OoxmlToHtmlConverter.document_to_html(self)
       end
+
+      private
+
+      # Ensure the document carries a theme part, creating it from a
+      # fresh parse of the bundled Office theme when absent (every
+      # document gets its own copy — no shared state).
+      #
+      # @param transformation [Themes::ThemeTransformation] Converter
+      # @return [void]
+      def ensure_theme!(transformation)
+        return if theme&.theme_elements
+
+        self.theme = transformation.default_office_theme
+      end
+
+      # Run model-level validation rules against this document.
+      #
+      # @return [Array<Validation::Report::ValidationIssue>] issues found
+      def structural_issues
+        Validation::Engine.run(Validation::Rules::ModelContext.new(self))
+      end
     end
   end
 end

data/lib/uniword/wordprocessingml/endnotes.rb

@@ -32,6 +32,10 @@ module Uniword
         end
 
         missing = endnote_entries.size - counts["endnote"]
+        return unless missing.positive?
+
+        # element_order from the parser may be frozen; never mutate it.
+        self.element_order = element_order.dup
         missing.times do
           element_order << Lutaml::Xml::Element.new("Element", "endnote")
         end

data/lib/uniword/wordprocessingml/font_replacer.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Wordprocessingml
+    # Replaces one font family with another across a document —
+    # Word's Home → Replace → Replace Fonts as an API.
+    #
+    # Covers style definitions and defaults, body content (paragraphs,
+    # tables, hyperlinks), headers and footers, footnotes, endnotes,
+    # comments, and numbering levels. Theme font references
+    # (asciiTheme/hAnsiTheme/...) are NOT rewritten — those are
+    # controlled by the theme's font scheme
+    # (see DocumentRoot#apply_font_scheme).
+    #
+    # @example Replace Calibri with Carlito throughout a document
+    #   replacer = FontReplacer.new(from: "Calibri", to: "Carlito")
+    #   replacer.replace(document)
+    #   puts replacer.count # number of rFonts values rewritten
+    class FontReplacer
+      # RunFonts attributes rewritten by font replacement.
+      FONT_ATTRIBUTES = %i[ascii h_ansi east_asia cs].freeze
+
+      # Create a replacer.
+      #
+      # @param from [String] Font family to replace (exact match,
+      #   Word semantics)
+      # @param to [String] Replacement font family
+      def initialize(from:, to:)
+        @from = from.to_s
+        @to = to.to_s
+        @count = 0
+      end
+
+      # Number of rFonts attribute values replaced so far.
+      #
+      # @return [Integer] Replacement count
+      attr_reader :count
+
+      # Replace @from with @to throughout the document (mutated).
+      #
+      # @param document [DocumentRoot] Document to rewrite
+      # @return [Integer] Replacement count
+      def replace(document)
+        replace_in_styles(document.styles_configuration)
+        replace_in_numbering(document.numbering_configuration)
+        replace_in_container(document.body)
+        part_containers(document).each do |container|
+          replace_in_paragraphs(container)
+        end
+        count
+      end
+
+      private
+
+      # Styles: docDefaults and every style definition.
+      def replace_in_styles(styles)
+        return unless styles
+
+        replace_in_run_properties(styles.doc_defaults&.rPrDefault&.rPr)
+        (styles.styles || []).each do |style|
+          replace_in_run_properties(style.rPr)
+        end
+      end
+
+      # Numbering: every level of every abstract definition.
+      def replace_in_numbering(numbering)
+        return unless numbering
+
+        (numbering.definitions || []).each do |definition|
+          (definition.levels || []).each do |level|
+            replace_in_run_properties(level.rPr)
+          end
+        end
+      end
+
+      # Containers outside the body: header/footer parts, note
+      # entries, and comments — model objects holding paragraphs.
+      def part_containers(document)
+        header_footer_containers(document) +
+          note_containers(document) + comment_containers(document)
+      end
+
+      def header_footer_containers(document)
+        (document.header_footer_parts || []).filter_map do |part|
+          part.content if part.content.is_a?(Lutaml::Model::Serializable)
+        end
+      end
+
+      def note_containers(document)
+        (document.footnotes&.footnote_entries || []) +
+          (document.endnotes&.endnote_entries || [])
+      end
+
+      def comment_containers(document)
+        document.comments&.comments || []
+      end
+
+      # Walk a container's paragraphs, recursing into (nested) tables.
+      def replace_in_container(container)
+        return unless container
+
+        replace_in_paragraphs(container)
+        (container.tables || []).each { |table| replace_in_table(table) }
+      end
+
+      def replace_in_table(table)
+        (table.rows || []).each do |row|
+          (row.cells || []).each { |cell| replace_in_container(cell) }
+        end
+      end
+
+      # Walk only paragraphs — for note/comment/header/footer parts,
+      # whose models do not expose nested tables.
+      def replace_in_paragraphs(container)
+        (container.paragraphs || []).each do |paragraph|
+          replace_in_paragraph(paragraph)
+        end
+      end
+
+      def replace_in_paragraph(paragraph)
+        replace_in_runs(paragraph.runs)
+        (paragraph.hyperlinks || []).each do |hyperlink|
+          replace_in_runs(hyperlink.runs)
+        end
+      end
+
+      def replace_in_runs(runs)
+        (runs || []).each do |run|
+          replace_in_run_properties(run.properties)
+        end
+      end
+
+      # Rewrite matching RunFonts attribute values in place.
+      def replace_in_run_properties(run_properties)
+        fonts = run_properties&.fonts
+        return unless fonts
+
+        FONT_ATTRIBUTES.each do |attr|
+          next unless fonts.method(attr).call == @from
+
+          fonts.method(:"#{attr}=").call(@to)
+          @count += 1
+        end
+      end
+    end
+  end
+end

data/lib/uniword/wordprocessingml/footnotes.rb

@@ -32,6 +32,10 @@ module Uniword
         end
 
         missing = footnote_entries.size - counts["footnote"]
+        return unless missing.positive?
+
+        # element_order from the parser may be frozen; never mutate it.
+        self.element_order = element_order.dup
         missing.times do
           element_order << Lutaml::Xml::Element.new("Element", "footnote")
         end

data/lib/uniword/wordprocessingml/hdr_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/hyperlink.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
-require "uniword/ooxml/types/relationship_id"
 
 module Uniword
   module Wordprocessingml

data/lib/uniword/wordprocessingml/level.rb

@@ -17,20 +17,6 @@ module Uniword
       end
     end
 
-    # Tabs container for numbering level
-    #
-    # Element: <w:tabs>
-    class Tabs < Lutaml::Model::Serializable
-      attribute :tab, Tab, collection: true
-
-      xml do
-        element "tabs"
-        namespace Uniword::Ooxml::Namespaces::WordProcessingML
-        mixed_content
-        map_element "tab", to: :tab, render_nil: false
-      end
-    end
-
     # Numbering level suffix type
     #
     # Element: <w:suff>
@@ -63,6 +49,10 @@ module Uniword
     #
     # Generated from OOXML schema: wordprocessingml.yml
     # Element: <w:lvl>
+    #
+    # Per ECMA-376 CT_Lvl, `w:ind` and `w:tabs` are NOT direct children of
+    # `w:lvl` — they belong to the level's `w:pPr`. They are therefore not
+    # mapped here; use `pPr.indentation` / `pPr.tabs`.
     class Level < Lutaml::Model::Serializable
       attribute :ilvl, :integer
       attribute :tentative, :string
@@ -75,8 +65,6 @@ module Uniword
       attribute :lvlText, LvlText
       attribute :lvlJc, LvlJc
       attribute :pPr, ParagraphProperties
-      attribute :tabs, Tabs
-      attribute :ind, Ind
       attribute :rPr, RunProperties
 
       xml do
@@ -95,8 +83,6 @@ module Uniword
         map_element "lvlText", to: :lvlText, render_nil: false
         map_element "lvlJc", to: :lvlJc, render_nil: false
         map_element "pPr", to: :pPr, render_nil: false
-        map_element "tabs", to: :tabs, render_nil: false
-        map_element "ind", to: :ind, render_nil: false
         map_element "rPr", to: :rPr, render_nil: false
       end
 
@@ -122,12 +108,12 @@ module Uniword
 
       # Get left indent (convenience method - returns integer)
       def left_indent_value
-        ind&.left&.to_i
+        pPr&.indentation&.left.to_i
       end
 
       # Get hanging indent (convenience method - returns integer)
       def hanging_indent_value
-        ind&.hanging&.to_i
+        pPr&.indentation&.hanging.to_i
       end
 
       # Get level text value (convenience method - returns string)

data/lib/uniword/wordprocessingml/math_pr.rb

@@ -1,17 +1,6 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
-require_relative "math_font"
-require_relative "brk_bin"
-require_relative "brk_bin_sub"
-require_relative "small_frac"
-require_relative "disp_def"
-require_relative "l_margin"
-require_relative "r_margin"
-require_relative "def_jc"
-require_relative "wrap_indent"
-require_relative "int_lim"
-require_relative "nary_lim"
 
 module Uniword
   module Wordprocessingml

data/lib/uniword/wordprocessingml/numbering_definition.rb

@@ -80,8 +80,10 @@ module Uniword
               start: Uniword::Wordprocessingml::Start.new(val: 1),
               numFmt: Uniword::Wordprocessingml::NumFmt.new(val: "decimal"),
               lvlJc: Uniword::Wordprocessingml::LvlJc.new(val: "left"),
-              ind: Uniword::Wordprocessingml::Ind.new(
-                left: (720 * (i + 1)).to_s, hanging: "360",
+              pPr: Uniword::Wordprocessingml::ParagraphProperties.new(
+                indentation: Uniword::Properties::Indentation.new(
+                  left: 720 * (i + 1), hanging: 360,
+                ),
               ),
             )
           end
@@ -104,8 +106,10 @@ module Uniword
               numFmt: Uniword::Wordprocessingml::NumFmt.new(val: "bullet"),
               lvlText: Uniword::Wordprocessingml::LvlText.new(val: level_char),
               lvlJc: Uniword::Wordprocessingml::LvlJc.new(val: "left"),
-              ind: Uniword::Wordprocessingml::Ind.new(
-                left: (720 * (i + 1)).to_s, hanging: "360",
+              pPr: Uniword::Wordprocessingml::ParagraphProperties.new(
+                indentation: Uniword::Properties::Indentation.new(
+                  left: 720 * (i + 1), hanging: 360,
+                ),
               ),
               rPr: Uniword::Wordprocessingml::RunProperties.new(
                 fonts: Properties::RunFonts.new(ascii: "Symbol",
@@ -126,8 +130,10 @@ module Uniword
               start: Uniword::Wordprocessingml::Start.new(val: 1),
               numFmt: Uniword::Wordprocessingml::NumFmt.new(val: format),
               lvlJc: Uniword::Wordprocessingml::LvlJc.new(val: "left"),
-              ind: Uniword::Wordprocessingml::Ind.new(
-                left: (720 * (i + 1)).to_s, hanging: "360",
+              pPr: Uniword::Wordprocessingml::ParagraphProperties.new(
+                indentation: Uniword::Properties::Indentation.new(
+                  left: 720 * (i + 1), hanging: 360,
+                ),
               ),
             )
           end
@@ -144,8 +150,10 @@ module Uniword
               start: Uniword::Wordprocessingml::Start.new(val: 1),
               numFmt: Uniword::Wordprocessingml::NumFmt.new(val: format),
               lvlJc: Uniword::Wordprocessingml::LvlJc.new(val: "left"),
-              ind: Uniword::Wordprocessingml::Ind.new(
-                left: (720 * (i + 1)).to_s, hanging: "360",
+              pPr: Uniword::Wordprocessingml::ParagraphProperties.new(
+                indentation: Uniword::Properties::Indentation.new(
+                  left: 720 * (i + 1), hanging: 360,
+                ),
               ),
             )
           end