uniword 1.2.5 → 1.3.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.
@@ -194,6 +194,14 @@ module Uniword
         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
+        document.comments = package.comments if package.comments
+        document.settings_rels = package.settings_rels if package.settings_rels
+        if package.footnotes_rels
+          document.footnotes_rels = package.footnotes_rels
+        end
+        if package.endnotes_rels
+          document.endnotes_rels = package.endnotes_rels
+        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,83 @@
+# 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
+
+      # 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

data/lib/uniword/docx/header_footer_part_collection.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Ordered collection of HeaderFooterPart objects — the single
+    # storage path for all header/footer parts of a document, whether
+    # loaded from an existing DOCX or added programmatically.
+    #
+    # The +headers+/+footers+ views (HeaderFooterView) and the
+    # serializer both read from this store, so a part exists exactly
+    # once: one part file, one relationship, one content-type
+    # override, one sectPr reference.
+    class HeaderFooterPartCollection
+      include Enumerable
+
+      def initialize
+        @parts = []
+      end
+
+      # Iterate over all parts (both kinds) in insertion order.
+      def each(&block)
+        @parts.each(&block)
+      end
+
+      # @return [Integer]
+      def size
+        @parts.size
+      end
+
+      alias length size
+
+      # @return [Boolean]
+      def empty?
+        @parts.empty?
+      end
+
+      # @return [Array<HeaderFooterPart>]
+      def to_a
+        @parts.dup
+      end
+
+      # Append a part.
+      #
+      # @param part [HeaderFooterPart]
+      # @return [HeaderFooterPart] the added part
+      def <<(part)
+        @parts << part
+        part
+      end
+
+      alias add <<
+
+      # Remove a part (by identity).
+      #
+      # @param part [HeaderFooterPart]
+      # @return [HeaderFooterPart, nil] the removed part
+      def delete(part)
+        @parts.delete(part)
+      end
+
+      # @param kind [Symbol] :header or :footer
+      # @return [Array<HeaderFooterPart>] parts of that kind, in order
+      def of_kind(kind)
+        @parts.select { |part| part.kind == kind }
+      end
+
+      # @param kind [Symbol] :header or :footer
+      # @param type [String, nil] sectPr reference type
+      # @return [HeaderFooterPart, nil]
+      def find_part(kind, type)
+        type = type&.to_s
+        @parts.find { |part| part.kind == kind && part.type == type }
+      end
+
+      # All non-nil relationship targets in the store.
+      #
+      # @return [Array<String>]
+      def targets
+        @parts.filter_map(&:target)
+      end
+
+      # First unused numbered target for a kind
+      # ("header3.xml" when header1/header2 exist).
+      #
+      # @param kind [Symbol] :header or :footer
+      # @return [String]
+      def next_target(kind)
+        numbers = of_kind(kind).filter_map do |part|
+          part.target&.[](/\A#{kind}(\d+)\.xml\z/, 1)&.to_i
+        end
+        "#{kind}#{(numbers.max || 0) + 1}.xml"
+      end
+
+      # Replace the entire store (legacy +header_footer_parts=+
+      # assignment). Accepts HeaderFooterPart objects and legacy
+      # part hashes ({ r_id:, target:, rel_type:, content_type:,
+      # content: }).
+      #
+      # @param parts [Array<HeaderFooterPart, Hash>]
+      # @return [void]
+      def replace_all(parts)
+        @parts = Array(parts).map { |part| self.class.wrap(part) }
+      end
+
+      # Replace all parts of one kind, leaving the other untouched.
+      #
+      # @param kind [Symbol] :header or :footer
+      # @param parts [Array<HeaderFooterPart>]
+      # @return [void]
+      def replace_kind(kind, parts)
+        @parts.reject! { |part| part.kind == kind }
+        parts.each { |part| @parts << part }
+      end
+
+      # Normalize one entry into a HeaderFooterPart. Legacy hashes
+      # describe loaded parts (they carry original rIds/targets).
+      #
+      # @param value [HeaderFooterPart, Hash]
+      # @return [HeaderFooterPart]
+      def self.wrap(value)
+        return value if value.is_a?(HeaderFooterPart)
+
+        HeaderFooterPart.new(
+          r_id: value[:r_id],
+          target: value[:target],
+          rel_type: value[:rel_type],
+          content_type: value[:content_type],
+          type: value[:type],
+          content: value[:content],
+          loaded: true,
+        )
+      end
+    end
+  end
+end