uniword 1.3.0 → 1.4.1

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

@@ -34,10 +34,9 @@ module Uniword
         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
+        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
 

data/lib/uniword/wordprocessingml/footnotes.rb

@@ -34,10 +34,9 @@ module Uniword
         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
+        order = Ooxml::ElementOrder.mutable_order(self)
         missing.times do
-          element_order << Lutaml::Xml::Element.new("Element", "footnote")
+          order << Lutaml::Xml::Element.new("Element", "footnote")
         end
       end
 

data/lib/uniword/wordprocessingml/numbering_elements.rb

@@ -30,21 +30,6 @@ module Uniword
       end
     end
 
-    # Indentation for numbering level
-    #
-    # Element: <w:ind>
-    class Ind < Lutaml::Model::Serializable
-      attribute :left, :string
-      attribute :hanging, :string
-
-      xml do
-        element "ind"
-        namespace Uniword::Ooxml::Namespaces::WordProcessingML
-        map_attribute "left", to: :left
-        map_attribute "hanging", to: :hanging
-      end
-    end
-
     # Run fonts for numbering
     #
     # Element: <w:rFonts>

data/lib/uniword/wordprocessingml.rb

@@ -4,6 +4,7 @@ module Uniword
   module Wordprocessingml
     # Core document structure
     autoload :DocumentRoot, "uniword/wordprocessingml/document_root"
+    autoload :DocumentStyling, "uniword/wordprocessingml/document_styling"
     autoload :Body, "uniword/wordprocessingml/body"
     autoload :Paragraph, "uniword/wordprocessingml/paragraph"
     autoload :Run, "uniword/wordprocessingml/run"
@@ -165,9 +166,7 @@ module Uniword
     autoload :NumFmt, "uniword/wordprocessingml/num_fmt"
     autoload :LvlText, "uniword/wordprocessingml/lvl_text"
     autoload :LvlJc, "uniword/wordprocessingml/lvl_jc"
-    autoload :Ind, "uniword/wordprocessingml/numbering_elements"
     autoload :RFonts, "uniword/wordprocessingml/numbering_elements"
-    autoload :Tabs, "uniword/wordprocessingml/level"
     autoload :PStyle, "uniword/wordprocessingml/level"
     autoload :NumberingConfiguration,
              "uniword/wordprocessingml/numbering_configuration"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uniword
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -822,13 +822,25 @@ files:
 - lib/uniword/docx/header_footer_part_collection.rb
 - lib/uniword/docx/header_footer_view.rb
 - lib/uniword/docx/id_allocator.rb
+- lib/uniword/docx/image_part.rb
 - lib/uniword/docx/package.rb
 - lib/uniword/docx/package_defaults.rb
 - lib/uniword/docx/package_integrity_checker.rb
 - lib/uniword/docx/package_serialization.rb
 - lib/uniword/docx/part.rb
 - lib/uniword/docx/part_collection.rb
+- lib/uniword/docx/part_loader.rb
+- lib/uniword/docx/part_loader/chart_loader.rb
+- lib/uniword/docx/part_loader/custom_xml_loader.rb
+- lib/uniword/docx/part_loader/embedding_loader.rb
+- lib/uniword/docx/part_loader/header_footer_loader.rb
+- lib/uniword/docx/part_loader/image_loader.rb
+- lib/uniword/docx/part_loader/load_context.rb
+- lib/uniword/docx/part_loader/raw_part_loader.rb
+- lib/uniword/docx/part_loader/theme_media_loader.rb
+- lib/uniword/docx/part_loader/xml_model_loader.rb
 - lib/uniword/docx/profile.rb
+- lib/uniword/docx/raw_part.rb
 - lib/uniword/docx/reconciler.rb
 - lib/uniword/docx/reconciler/body.rb
 - lib/uniword/docx/reconciler/fix.rb
@@ -1109,6 +1121,7 @@ files:
 - lib/uniword/ooxml/core_properties.rb
 - lib/uniword/ooxml/custom_properties.rb
 - lib/uniword/ooxml/dotx_package.rb
+- lib/uniword/ooxml/element_order.rb
 - lib/uniword/ooxml/namespaces.rb
 - lib/uniword/ooxml/package_file.rb
 - lib/uniword/ooxml/part_definition.rb
@@ -1669,6 +1682,7 @@ files:
 - lib/uniword/wordprocessingml/doc_vars.rb
 - lib/uniword/wordprocessingml/document_root.rb
 - lib/uniword/wordprocessingml/document_root/feature_facade.rb
+- lib/uniword/wordprocessingml/document_styling.rb
 - lib/uniword/wordprocessingml/drawing.rb
 - lib/uniword/wordprocessingml/emboss.rb
 - lib/uniword/wordprocessingml/endnote.rb