uniword 1.2.5 → 1.4.0

data/lib/uniword/configuration.rb

@@ -1,8 +1,100 @@
 # frozen_string_literal: true
 
 module Uniword
-  module Configuration
+  # Global runtime configuration for Uniword.
+  #
+  # Holds save-path policy as plain, explicitly typed boolean attributes.
+  # This object is runtime policy only: it has no file-loading behavior
+  # (see ConfigurationLoader for external YAML config files) and no
+  # serialization behavior.
+  #
+  # This class also serves as the namespace for configuration-related
+  # classes (ConfigurationLoader, ConfigurationError).
+  #
+  # @example Read current policy
+  #   Uniword.configuration.validate_on_save # => true
+  #
+  # @example Change policy via Uniword.configure
+  #   Uniword.configure do |config|
+  #     config.xsd_validation = true
+  #   end
+  class Configuration
     autoload :ConfigurationLoader,
              "#{__dir__}/configuration/configuration_loader"
+
+    # Whether documents are validated when saved.
+    #
+    # @return [Boolean]
+    attr_reader :validate_on_save
+
+    # Whether XSD schema validation runs on save (slower, stricter).
+    #
+    # @return [Boolean]
+    attr_reader :xsd_validation
+
+    # Whether automatic fixes applied during save are logged.
+    #
+    # @return [Boolean]
+    attr_reader :log_save_fixes
+
+    # Create a configuration with default policy values.
+    #
+    # Defaults: validate_on_save: true, xsd_validation: false,
+    # log_save_fixes: true.
+    def initialize
+      reset!
+    end
+
+    # Restore all attributes to their default values.
+    #
+    # @return [Configuration] self
+    def reset!
+      @validate_on_save = true
+      @xsd_validation = false
+      @log_save_fixes = true
+      self
+    end
+
+    # Set the validate-on-save policy.
+    #
+    # @param value [Boolean] new value
+    # @return [Boolean] the value set
+    # @raise [ArgumentError] if value is not true or false
+    def validate_on_save=(value)
+      @validate_on_save = typed_boolean(value, :validate_on_save)
+    end
+
+    # Set the XSD validation policy.
+    #
+    # @param value [Boolean] new value
+    # @return [Boolean] the value set
+    # @raise [ArgumentError] if value is not true or false
+    def xsd_validation=(value)
+      @xsd_validation = typed_boolean(value, :xsd_validation)
+    end
+
+    # Set the save-fix logging policy.
+    #
+    # @param value [Boolean] new value
+    # @return [Boolean] the value set
+    # @raise [ArgumentError] if value is not true or false
+    def log_save_fixes=(value)
+      @log_save_fixes = typed_boolean(value, :log_save_fixes)
+    end
+
+    private
+
+    # Validate that a value is strictly boolean.
+    #
+    # @param value [Object] value to check
+    # @param name [Symbol] attribute name used in the error message
+    # @return [Boolean] the value
+    # @raise [ArgumentError] if value is not true or false
+    def typed_boolean(value, name)
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      raise ArgumentError,
+            "#{name} must be true or false, got #{value.inspect}"
+    end
   end
 end

data/lib/uniword/content_types.rb

@@ -16,41 +16,20 @@ module Uniword
     #
     # Generate comprehensive [Content_Types].xml
     #
+    # Derived from Ooxml::PartRegistry (:standard definitions, in
+    # registration order — historically the literal order below).
+    #
     # @return [Types] Content types object
     def generate
       Types.new(
-        defaults: [
-          Default.new(extension: "jpeg",
-                      content_type: "image/jpeg"),
-          Default.new(extension: "png",
-                      content_type: "image/png"),
-          Default.new(extension: "gif",
-                      content_type: "image/gif"),
-          Default.new(extension: "rels",
-                      content_type: "application/vnd.openxmlformats-package.relationships+xml"),
-          Default.new(extension: "xml",
-                      content_type: "application/xml"),
-        ],
-        overrides: [
-          Override.new(part_name: "/word/document.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"),
-          Override.new(part_name: "/word/numbering.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"),
-          Override.new(part_name: "/word/styles.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"),
-          Override.new(part_name: "/word/settings.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml"),
-          Override.new(part_name: "/word/webSettings.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.webSettings+xml"),
-          Override.new(part_name: "/word/fontTable.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml"),
-          Override.new(part_name: "/word/theme/theme1.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.theme+xml"),
-          Override.new(part_name: "/docProps/core.xml",
-                       content_type: "application/vnd.openxmlformats-package.core-properties+xml"),
-          Override.new(part_name: "/docProps/app.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.extended-properties+xml"),
-        ],
+        defaults: Ooxml::PartRegistry.standard_defaults.map do |defn|
+          Default.new(extension: defn.extension,
+                      content_type: defn.content_type)
+        end,
+        overrides: Ooxml::PartRegistry.standard_overrides.map do |defn|
+          Override.new(part_name: defn.part_name,
+                       content_type: defn.content_type)
+        end,
       )
     end
     module_function :generate
@@ -59,15 +38,16 @@ module Uniword
     #
     # @return [Types] Content types object for theme package
     def generate_for_theme
+      theme = Ooxml::PartRegistry.find_by_key(:thmx_theme)
       Types.new(
-        defaults: [
-          Default.new(extension: "rels",
-                      content_type: "application/vnd.openxmlformats-package.relationships+xml"),
-          Default.new(extension: "xml", content_type: "application/xml"),
-        ],
+        defaults: %i[rels xml].map do |key|
+          defn = Ooxml::PartRegistry.find_by_key(key)
+          Default.new(extension: defn.extension,
+                      content_type: defn.content_type)
+        end,
         overrides: [
-          Override.new(part_name: "/theme/theme1.xml",
-                       content_type: "application/vnd.openxmlformats-officedocument.theme+xml"),
+          Override.new(part_name: theme.part_name,
+                       content_type: theme.content_type),
         ],
       )
     end

data/lib/uniword/document_factory.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # All classes autoloaded via lib/uniword.rb
-# No require_relative needed - autoload handles lazy loading
+# Lazy loading for internal library code is handled by autoload.
 
 module Uniword
   # Factory for creating Document instances.
@@ -169,31 +169,25 @@ module Uniword
         detector.detect(path)
       end
 
-
       # Copy package parts to document for round-trip preservation
       #
+      # Registry-driven: every PartDefinition naming both a package
+      # and a document attribute (and not excluded via
+      # +copy_to_document: false+) is mirrored; a part can no longer
+      # exist in only one direction.
+      #
       # @param package [Docx::Package] The source package
       # @param document [Wordprocessingml::DocumentRoot] The target document
       # @return [void]
       def copy_package_parts_to_document(package, document)
         return unless document.is_a?(Uniword::Wordprocessingml::DocumentRoot)
 
-        document.styles_configuration = package.styles if package.styles
-        document.numbering_configuration = package.numbering if package.numbering
-        document.settings = package.settings if package.settings
-        document.font_table = package.font_table if package.font_table
-        document.web_settings = package.web_settings if package.web_settings
-        document.theme = package.theme if package.theme
-        document.core_properties = package.core_properties if package.core_properties
-        document.app_properties = package.app_properties if package.app_properties
-        document.document_rels = package.document_rels if package.document_rels
-        document.theme_rels = package.theme_rels if package.theme_rels
-        document.package_rels = package.package_rels if package.package_rels
-        document.content_types = package.content_types if package.content_types
-        document.custom_properties = package.custom_properties if package.custom_properties
-        document.custom_xml_items = package.custom_xml_items if package.custom_xml_items
-        document.footnotes = package.footnotes if package.footnotes
-        document.endnotes = package.endnotes if package.endnotes
+        Ooxml::PartRegistry.copied_to_document.each do |definition|
+          value = package.method(definition.package_attribute).call
+          next if value.nil?
+
+          document.method(:"#{definition.document_attribute}=").call(value)
+        end
       end
 
       private

data/lib/uniword/document_writer.rb

@@ -33,25 +33,34 @@ module Uniword
     #
     # @param path [String] The output file path
     # @param format [Symbol] The format (:auto, :docx, :mhtml)
+    # @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.
+    #   Not applicable to :mhtml (MIME, not an OPC/ZIP package — there are
+    #   no content types, relationships parts, or ZIP entries to check).
     # @return [void]
     # @raise [ArgumentError] if path is invalid
     # @raise [ArgumentError] if format is not supported
+    # @raise [Uniword::ValidationError] when the gate is enabled and the
+    #   generated package content is invalid
     #
     # @example Save as DOCX
     #   writer.save("output.docx")
     #
     # @example Save with explicit format
     #   writer.save("output.mht", format: :mhtml)
-    def save(path, format: :auto, profile: nil)
+    def save(path, format: :auto, profile: nil, validate: nil)
       validate_path(path)
 
       format = infer_format(path) if format == :auto
 
       case format
       when :docx, :docm
-        Docx::Package.to_file(document, path, profile: profile)
+        Docx::Package.to_file(document, path, profile: profile,
+                                            validate: validate)
       when :dotx, :dotm
-        Ooxml::DotxPackage.to_file(document, path, profile: profile)
+        Ooxml::DotxPackage.to_file(document, path, profile: profile,
+                                                 validate: validate)
       when :mhtml
         Mhtml::MhtmlPackage.to_file(document, path)
       else
@@ -99,6 +108,8 @@ module Uniword
     #
     # @param stream [IO, StringIO] The output stream
     # @param format [Symbol] The format (:docx, :mhtml)
+    # @param validate [Boolean, nil] Run the package integrity gate before
+    #   writing; nil falls back to Uniword.configuration.validate_on_save
     # @return [void]
     #
     # @example Write to StringIO
@@ -106,14 +117,14 @@ module Uniword
     #   writer.write_to_stream(io)
     #   io.rewind
     #   content = io.read
-    def write_to_stream(stream, format: :docx)
+    def write_to_stream(stream, format: :docx, validate: nil)
       require "tempfile"
 
       # Use a temporary file to generate the document
       temp_file = Tempfile.new(["uniword_stream", ".#{format}"], binmode: true)
       begin
         # Save to temp file
-        save(temp_file.path, format: format)
+        save(temp_file.path, format: format, validate: validate)
 
         # Read and write to stream in binary mode
         temp_file.rewind

data/lib/uniword/docx/chart_part.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # A chart part (word/charts/chartN.xml) held by the package.
+    #
+    # The content is the raw chart XML String. Replaces the former
+    # +{ xml:, target: }+ hash entries in +chart_parts+.
+    class ChartPart < Part
+      # @param r_id [String, nil] relationship id
+      # @param target [String, nil] e.g. "charts/chart1.xml"
+      # @param content [String, nil] raw chart XML
+      def initialize(r_id: nil, target: nil, content: nil, **rest)
+        super(
+          definition: Ooxml::PartRegistry.find_by_key(:chart),
+          r_id: r_id, target: target, content: content, **rest
+        )
+      end
+
+      # Raw chart XML (alias for content).
+      #
+      # @return [String, nil]
+      def xml
+        content
+      end
+
+      # Hash-style read compatibility (+:xml+ in addition to the
+      # Part keys).
+      def [](key)
+        key.to_sym == :xml ? content : super
+      end
+    end
+  end
+end

data/lib/uniword/docx/custom_xml_item.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # One customXml data item (customXml/itemN.xml) with its optional
+    # properties part and relationships part.
+    #
+    # Replaces the former +{ index:, xml_content:, props_xml:,
+    # rels_xml: }+ hash entries in +custom_xml_items+.
+    class CustomXmlItem
+      # @return [Integer] item number (customXml/item%<index>d.xml)
+      attr_accessor :index
+
+      # @return [String] raw XML of the item part
+      attr_accessor :xml_content
+
+      # @return [String, nil] raw XML of the itemProps part
+      attr_accessor :props_xml
+
+      # @return [String, nil] raw XML of the item relationships part
+      attr_accessor :rels_xml
+
+      # @param index [Integer] item number
+      # @param xml_content [String] raw item XML
+      # @param props_xml [String, nil] raw itemProps XML
+      # @param rels_xml [String, nil] raw item relationships XML
+      def initialize(index:, xml_content:, props_xml: nil, rels_xml: nil)
+        @index = index
+        @xml_content = xml_content
+        @props_xml = props_xml
+        @rels_xml = rels_xml
+      end
+
+      # Normalize a legacy hash entry (or an existing CustomXmlItem)
+      # into a CustomXmlItem.
+      #
+      # @param value [CustomXmlItem, Hash]
+      # @return [CustomXmlItem]
+      def self.wrap(value)
+        return value if value.is_a?(CustomXmlItem)
+
+        new(
+          index: value[:index],
+          xml_content: value[:xml_content],
+          props_xml: value[:props_xml],
+          rels_xml: value[:rels_xml],
+        )
+      end
+
+      # Package path of the item part.
+      #
+      # @return [String] e.g. "customXml/item1.xml"
+      def path
+        Ooxml::PartRegistry.find_by_key(:custom_xml_item)
+          .path_for(index: index)
+      end
+
+      # Package path of the properties part.
+      #
+      # @return [String, nil] e.g. "customXml/itemProps1.xml"
+      def props_path
+        return nil unless props_xml
+
+        Ooxml::PartRegistry.find_by_key(:custom_xml_item_props)
+          .path_for(index: index)
+      end
+
+      # Package paths this item emits (item part plus its properties
+      # part when present).
+      #
+      # @return [Array<String>] emitted package paths
+      def package_paths
+        [path, props_path].compact
+      end
+
+      # Hash-style read compatibility.
+      #
+      # @param key [Symbol, String] one of :index, :xml_content,
+      #   :props_xml, :rels_xml
+      # @return [Object, nil]
+      def [](key)
+        case key.to_sym
+        when :index then index
+        when :xml_content then xml_content
+        when :props_xml then props_xml
+        when :rels_xml then rels_xml
+        end
+      end
+    end
+  end
+end

data/lib/uniword/docx/header_footer_part.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # A header or footer part (word/headerN.xml / word/footerN.xml)
+    # held by the package — the single storage form for both
+    # round-tripped and builder-created headers/footers.
+    #
+    # Parts loaded from an existing DOCX carry their original +r_id+,
+    # +target+ and +rel_type+ verbatim and are flagged +loaded+ so the
+    # reconciler leaves their relationships and section references
+    # untouched. Parts added programmatically (via the Builder or the
+    # +headers+/+footers+ views) are flagged fresh: the reconciler
+    # assigns them a relationship and wires the sectPr reference.
+    #
+    # The +type+ ("default"/"first"/"even") is the sectPr reference
+    # type — derived from the section properties on load, set by the
+    # caller on insert. Content is usually a
+    # Wordprocessingml::Header or Wordprocessingml::Footer model;
+    # legacy Uniword::Header/Uniword::Footer convenience models are
+    # stored as given and converted at serialization time so callers
+    # can keep mutating the object they inserted.
+    class HeaderFooterPart < Part
+      # Valid section reference types.
+      TYPES = %w[default first even].freeze
+
+      # @return [String, nil] sectPr reference type
+      #   ("default"/"first"/"even")
+      attr_accessor :type
+
+      # @param kind [Symbol, nil] :header or :footer (derived from
+      #   rel_type, target or content when omitted)
+      # @param type [String, nil] sectPr reference type
+      # @param loaded [Boolean] true when extracted verbatim from an
+      #   existing package
+      def initialize(kind: nil, type: nil, loaded: false, **rest)
+        super(**rest)
+        @kind = kind
+        @type = type&.to_s
+        @loaded = loaded
+      end
+
+      # @return [Symbol, nil] :header or :footer
+      def kind
+        @kind ||= derive_kind
+      end
+
+      # @return [Boolean] true for header parts
+      def header?
+        kind == :header
+      end
+
+      # @return [Boolean] true for footer parts
+      def footer?
+        kind == :footer
+      end
+
+      # @return [Boolean] true when extracted from an existing package
+      #   (relationships and section references are already in place)
+      def loaded?
+        !!@loaded
+      end
+
+      # Mark whether the part originates from a loaded package.
+      attr_writer :loaded
+
+      # Registry definition for this part kind.
+      #
+      # @return [Ooxml::PartDefinition, nil]
+      def definition
+        @definition ||= kind && Ooxml::PartRegistry.find_by_key(kind)
+      end
+
+      # -- Content delegation (quacks like the content model) --
+
+      # @return [Array<Wordprocessingml::Paragraph>] content paragraphs
+      def paragraphs
+        content&.paragraphs
+      end
+
+      # @return [Array<Wordprocessingml::Table>] content tables
+      def tables
+        content&.tables
+      end
+
+      # @return [Boolean] true when the content has no paragraphs/tables
+      def empty?
+        return true unless content
+
+        paragraphs.empty? && tables.empty?
+      end
+
+      # Hash-style read compatibility (+:type+ in addition to the
+      # Part keys).
+      def [](key)
+        key.to_sym == :type ? type : super
+      end
+
+      # The content model to serialize into the part file. Legacy
+      # Uniword::Header/Uniword::Footer models are converted to their
+      # Wordprocessingml counterparts (paragraph and table elements are
+      # shared, mc:Ignorable carried over); other content passes
+      # through unchanged.
+      #
+      # @return [Object] serializable content model
+      def serializable_content
+        case content
+        when Uniword::Header
+          convert_legacy(Wordprocessingml::Header.new)
+        when Uniword::Footer
+          convert_legacy(Wordprocessingml::Footer.new)
+        else
+          content
+        end
+      end
+
+      private
+
+      def convert_legacy(wml)
+        wml.paragraphs.concat(content.paragraphs)
+        wml.tables.concat(content.tables)
+        wml.mc_ignorable = content.mc_ignorable if content.mc_ignorable
+        wml
+      end
+
+      def derive_kind
+        # rel_type (".../relationships/header") and target
+        # ("header1.xml") both embed the kind word.
+        carrier = "#{rel_type} #{target}"
+        return :header if carrier.include?("header")
+        return :footer if carrier.include?("footer")
+
+        case content
+        when Wordprocessingml::Header, Uniword::Header then :header
+        when Wordprocessingml::Footer, Uniword::Footer then :footer
+        end
+      end
+    end
+  end
+end