uniword 1.2.5 → 1.4.0

data/lib/uniword/wordprocessingml/document_root.rb

@@ -12,6 +12,7 @@ module Uniword
       autoload :FeatureFacade, "#{__dir__}/document_root/feature_facade"
 
       include FeatureFacade
+      include DocumentStyling
       include Uniword::DocumentInput
 
       attribute :mc_ignorable, Uniword::Ooxml::Types::McIgnorable
@@ -94,28 +95,14 @@ 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 +110,100 @@ 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
+
+      # Image parts (word/media/* binaries), keyed by rId.
+      #
+      # @return [Docx::PartCollection] rId => Docx::ImagePart
+      def image_parts
+        @image_parts ||= Docx::PartCollection.new(:r_id, Docx::ImagePart)
+      end
+
+      # Bulk-assign image parts (Hash of rId => ImagePart/legacy part
+      # hash; nil clears).
+      def image_parts=(value)
+        image_parts.replace_all(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
+
+      # Raw passthrough parts (unmodelled package parts carried
+      # byte-for-byte), keyed by package path. Mirrored from the
+      # package on load and back on save via the registry-driven
+      # document↔package copies (:raw_parts definition).
+      #
+      # @return [Docx::PartCollection] package path => Docx::RawPart
+      def raw_parts
+        @raw_parts ||= Docx::PartCollection.new(:path, Docx::RawPart)
+      end
+
+      # Bulk-assign raw parts (Hash of path => RawPart/hash; nil clears).
+      def raw_parts=(value)
+        raw_parts.replace_all(value)
+      end
+
       # Get app_properties (lazy initialization)
       #
       # @return [Uniword::Ooxml::AppProperties] The app properties object
@@ -168,17 +249,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 +314,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
@@ -265,104 +353,6 @@ module Uniword
 
       # Apply theme to document
       #
-      # Applies a Uniword theme by name, updating doc defaults and
-      # built-in heading/hyperlink styles to reference the theme.
-      #
-      # @param name [String, Symbol] Theme slug (e.g., 'meridian', 'corporate')
-      # @param options [Hash] optional overrides
-      # @option options [Hash] :colors override specific color keys
-      # @option options [String] :major_font override major font
-      # @option options [String] :minor_font override minor font
-      # @return [self] For method chaining
-      def apply_theme(name, **options)
-        friendly = Themes::Theme.load(name.to_s)
-
-        options[:colors]&.each do |key, value|
-          friendly.color_scheme[key.to_s] = value
-        end
-        friendly.font_scheme.major_font = options[:major_font] if options[:major_font]
-        friendly.font_scheme.minor_font = options[:minor_font] if options[:minor_font]
-
-        word_theme = Themes::ThemeTransformation.new.to_word(friendly)
-        Themes::ThemeApplicator.new.apply(word_theme, self)
-        self
-      end
-
-      # Apply theme from .thmx file
-      #
-      # @param path [String] Path to .thmx file
-      # @param variant [String, Integer, nil] Optional variant
-      # @return [self] For method chaining
-      def apply_theme_file(path, variant: nil)
-        loader = Themes::ThemeLoader.new
-        self.theme = if variant
-                       loader.load_with_variant(path, variant)
-                     else
-                       loader.load(path)
-                     end
-        self
-      end
-
-      # Apply StyleSet to document
-      #
-      # @param name [String, Symbol] StyleSet slug (e.g., 'signature', 'heritage')
-      # @param strategy [Symbol] Application strategy (:keep_existing, :replace, :rename)
-      # @return [self] For method chaining
-      def apply_styleset(name, strategy: :keep_existing)
-        styleset = Uniword::Stylesets::YamlStyleSetLoader.load_bundled(name.to_s)
-        styleset.apply_to(self, strategy: strategy)
-        self
-      end
-
-      # Auto-transition from MS theme to Uniword equivalent
-      #
-      # Detects the MS theme in the document's embedded theme and replaces
-      # it with the corresponding Uniword theme (font-substituted, renamed).
-      #
-      # @return [Hash, nil] { uniword_slug:, ms_name: } or nil if no match
-      #
-      # @example
-      #   result = doc.auto_transition_theme
-      #   puts "Transitioned from #{result[:ms_name]} to #{result[:uniword_slug]}"
-      def auto_transition_theme
-        Resource::ThemeTransition.auto_transition!(self)
-      end
-
-      # Apply theme from another document
-      #
-      # @param source_path [String] Path to source .docx file
-      # @return [self] For method chaining
-      def apply_theme_from(source_path)
-        source_doc = Uniword.load(source_path)
-        self.theme = source_doc.theme.dup if source_doc.theme
-        self
-      end
-
-      # Apply styles from another document
-      #
-      # @param source_path [String] Path to source .docx file
-      # @param strategy [Symbol] Conflict resolution strategy
-      # @return [self] For method chaining
-      def apply_styles_from(source_path, strategy: :keep_existing)
-        source_doc = Uniword.load(source_path)
-        styles_configuration.merge(source_doc.styles_configuration,
-                                   conflict_resolution: strategy)
-        self
-      end
-
-      # Apply both theme and styles from a template document
-      #
-      # @param template_path [String] Path to template .docx file
-      # @param strategy [Symbol] Conflict resolution strategy for styles
-      # @return [self] For method chaining
-      def apply_template(template_path, strategy: :keep_existing)
-        template_doc = Uniword.load(template_path)
-        self.theme = template_doc.theme.dup if template_doc.theme
-        styles_configuration.merge(template_doc.styles_configuration,
-                                   conflict_resolution: strategy)
-        self
-      end
-
       # Custom inspect for readable output
       #
       # @return [String] Human-readable representation
@@ -376,6 +366,15 @@ module Uniword
       def to_html_document
         Uniword::Transformation::OoxmlToHtmlConverter.document_to_html(self)
       end
+
+      private
+
+      # 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/document_styling.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Wordprocessingml
+    # Theme and style application for DocumentRoot — Word's
+    # Design/Layout/Styles surfaces as document-level API.
+    #
+    # Extracted from DocumentRoot to keep the document model focused:
+    # bundled and file-based theme application, stylesets, font and
+    # color schemes, font replacement, page setup, and style
+    # management (rename/remove).
+    module DocumentStyling
+      # Applies a Uniword theme by name, updating doc defaults and
+      # built-in heading/hyperlink styles to reference the theme.
+      #
+      # @param name [String, Symbol] Theme slug (e.g., 'meridian',
+      #   'corporate')
+      # @param options [Hash] optional overrides
+      # @option options [Hash] :colors override specific color keys
+      # @option options [String] :major_font override major font
+      # @option options [String] :minor_font override minor font
+      # @return [self] For method chaining
+      def apply_theme(name, **options)
+        friendly = Themes::Theme.load(name.to_s)
+
+        options[:colors]&.each do |key, value|
+          friendly.color_scheme[key.to_s] = value
+        end
+        if options[:major_font]
+          friendly.font_scheme.major_font = options[:major_font]
+        end
+        if options[:minor_font]
+          friendly.font_scheme.minor_font = options[:minor_font]
+        end
+
+        word_theme = Themes::ThemeTransformation.new.to_word(friendly)
+        Themes::ThemeApplicator.new.apply(word_theme, self)
+        self
+      end
+
+      # Apply theme from .thmx file
+      #
+      # @param path [String] Path to .thmx file
+      # @param variant [String, Integer, nil] Optional variant
+      # @return [self] For method chaining
+      def apply_theme_file(path, variant: nil)
+        loader = Themes::ThemeLoader.new
+        self.theme = if variant
+                       loader.load_with_variant(path, variant)
+                     else
+                       loader.load(path)
+                     end
+        self
+      end
+
+      # Apply StyleSet to document
+      #
+      # @param name [String, Symbol] StyleSet slug (e.g., 'signature',
+      #   'heritage')
+      # @param strategy [Symbol] Application strategy (:keep_existing,
+      #   :replace, :rename)
+      # @return [self] For method chaining
+      def apply_styleset(name, strategy: :keep_existing)
+        styleset = Uniword::Stylesets::YamlStyleSetLoader
+          .load_bundled(name.to_s)
+        styleset.apply_to(self, strategy: strategy)
+        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 [Style, nil] The removed style, or nil when not
+      #   removed (absent or protected)
+      def remove_style(style_id)
+        style = styles_configuration.style(style_id)
+        return unless StyleCleanup.new(self).remove?(style_id)
+
+        style
+      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
+      # it with the corresponding Uniword theme (font-substituted, renamed).
+      #
+      # @return [Hash, nil] { uniword_slug:, ms_name: } or nil if no match
+      #
+      # @example
+      #   result = doc.auto_transition_theme
+      #   puts "Transitioned from " \
+      #        "#{result[:ms_name]} to #{result[:uniword_slug]}"
+      def auto_transition_theme
+        Resource::ThemeTransition.auto_transition!(self)
+      end
+
+      # Apply theme from another document
+      #
+      # @param source_path [String] Path to source .docx file
+      # @return [self] For method chaining
+      def apply_theme_from(source_path)
+        source_doc = Uniword.load(source_path)
+        self.theme = source_doc.theme.dup if source_doc.theme
+        self
+      end
+
+      # Apply styles from another document
+      #
+      # @param source_path [String] Path to source .docx file
+      # @param strategy [Symbol] Conflict resolution strategy
+      # @return [self] For method chaining
+      def apply_styles_from(source_path, strategy: :keep_existing)
+        source_doc = Uniword.load(source_path)
+        styles_configuration.merge(source_doc.styles_configuration,
+                                   conflict_resolution: strategy)
+        self
+      end
+
+      # Apply both theme and styles from a template document
+      #
+      # @param template_path [String] Path to template .docx file
+      # @param strategy [Symbol] Conflict resolution strategy for styles
+      # @return [self] For method chaining
+      def apply_template(template_path, strategy: :keep_existing)
+        template_doc = Uniword.load(template_path)
+        self.theme = template_doc.theme.dup if template_doc.theme
+        styles_configuration.merge(template_doc.styles_configuration,
+                                   conflict_resolution: strategy)
+        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
+    end
+  end
+end

data/lib/uniword/wordprocessingml/endnotes.rb

@@ -32,8 +32,11 @@ module Uniword
         end
 
         missing = endnote_entries.size - counts["endnote"]
+        return unless missing.positive?
+
+        order = Ooxml::ElementOrder.mutable_order(self)
         missing.times do
-          element_order << Lutaml::Xml::Element.new("Element", "endnote")
+          order << Lutaml::Xml::Element.new("Element", "endnote")
         end
       end