uniword 1.0.0

data/lib/uniword/footer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  # Represents a document footer
+  # Footers can contain paragraphs, tables, and fields (like page numbers)
+  class Footer < Lutaml::Model::Serializable
+    attribute :type, :string, default: -> { 'default' }
+    attribute :paragraphs, Wordprocessingml::Paragraph, collection: true, initialize_empty: true
+    attribute :tables, Wordprocessingml::Table, collection: true, initialize_empty: true
+
+    # Valid footer types
+    TYPES = %w[default first even].freeze
+
+    def initialize(**attributes)
+      super
+      validate_type
+    end
+
+    # Get all content elements (paragraphs and tables) in order
+    def elements
+      (paragraphs + tables).sort_by do |elem|
+        paragraphs.index(elem) || (tables.index(elem) + paragraphs.size)
+      end
+    end
+
+    # Check if footer is empty
+    def empty?
+      paragraphs.empty? && tables.empty?
+    end
+
+    private
+
+    def validate_type
+      return unless type && !TYPES.include?(type)
+
+      raise ArgumentError, "Invalid footer type: #{type}. Must be one of: #{TYPES.join(', ')}"
+    end
+  end
+end

data/lib/uniword/footnote.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Represents a footnote in a document.
+  #
+  # Responsibility: Store footnote content and metadata. Footnotes appear
+  # at the bottom of the page where they are referenced.
+  #
+  # A footnote consists of:
+  # - An ID that uniquely identifies it
+  # - Content (array of paragraphs)
+  #
+  # @example Create a footnote
+  #   footnote = Uniword::Footnote.new(
+  #     id: 1,
+  #     content: [paragraph1, paragraph2]
+  #   )
+  #
+  # @example Access footnote properties
+  #   footnote.id       # => 1
+  #   footnote.content  # => [paragraph1, paragraph2]
+  class Footnote
+    # @return [Integer, String] The unique identifier for this footnote
+    attr_accessor :id
+
+    # @return [Array<Paragraph>] The content paragraphs of the footnote
+    attr_accessor :content
+
+    # Initialize a new Footnote.
+    #
+    # @param id [Integer, String] The unique identifier
+    # @param content [Array<Paragraph>] The footnote content paragraphs
+    #
+    # @example Create a footnote
+    #   footnote = Footnote.new(id: 1, content: [paragraph])
+    def initialize(id:, content: [])
+      @id = id
+      @content = content
+    end
+
+    # Check if footnote has content.
+    #
+    # @return [Boolean] true if footnote has content
+    def content?
+      !@content.nil? && !@content.empty?
+    end
+
+    # Get text content of footnote.
+    #
+    # @return [String] The combined text of all paragraphs
+    def text
+      @content.map { |p| p.respond_to?(:text) ? p.text : p.to_s }.join("\n")
+    end
+
+    # Convert to hash representation.
+    #
+    # @return [Hash] Hash representation of the footnote
+    def to_h
+      {
+        id: @id,
+        content: @content
+      }
+    end
+  end
+end

data/lib/uniword/format_converter.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+# All classes autoloaded via lib/uniword.rb
+# Transformation::Transformer, DocumentFactory, DocumentWriter
+
+module Uniword
+  # Explicit format converter with declarative API.
+  #
+  # Responsibility: Coordinate format conversion using model transformation.
+  # Single Responsibility - orchestrates conversion, delegates implementation.
+  #
+  # Architecture follows separation of concerns:
+  # 1. Reading (DocumentFactory) - separate from transformation
+  # 2. Transformation (Transformer) - separate from I/O
+  # 3. Writing (DocumentWriter) - separate from transformation
+  #
+  # Provides explicit, declarative API with no magic or automatic detection.
+  #
+  # @example Explicit DOCX to MHTML conversion
+  #   converter = Uniword::FormatConverter.new
+  #   result = converter.convert(
+  #     source: "input.docx",
+  #     source_format: :docx,
+  #     target: "output.mhtml",
+  #     target_format: :mhtml
+  #   )
+  #
+  # @example Named conversion method
+  #   result = converter.docx_to_mhtml(
+  #     source: "document.docx",
+  #     target: "document.mhtml"
+  #   )
+  class FormatConverter
+    # Initialize a new format converter
+    #
+    # @param options [Hash] Converter options
+    # @option options [Logger] :logger (nil) Logger for conversion progress
+    # @option options [Boolean] :preserve_metadata (true) Preserve styles/theme
+    # @option options [Transformation::Transformer] :transformer (nil) Custom transformer
+    def initialize(options = {})
+      @logger = options[:logger]
+      @preserve_metadata = options.fetch(:preserve_metadata, true)
+      @transformer = options[:transformer] || Transformation::Transformer.new
+    end
+
+    # Convert between formats with explicit specification.
+    #
+    # All parameters must be explicitly specified - no automatic detection.
+    #
+    # @param source [String, IO] Source file path or stream
+    # @param source_format [Symbol] Source format (:docx or :mhtml)
+    # @param target [String, IO] Target file path or stream
+    # @param target_format [Symbol] Target format (:docx or :mhtml)
+    # @param options [Hash] Conversion options
+    # @option options [Boolean] :preserve_images (true) Preserve images
+    # @option options [Boolean] :preserve_formatting (true) Preserve formatting
+    # @return [ConversionResult] Result object with statistics
+    # @raise [ArgumentError] if parameters are invalid
+    #
+    # @example Explicit conversion
+    #   result = converter.convert(
+    #     source: "input.mhtml",
+    #     source_format: :mhtml,
+    #     target: "output.docx",
+    #     target_format: :docx
+    #   )
+    #   puts result  # "Conversion: mhtml → docx (SUCCESS)"
+    def convert(source:, source_format:, target:, target_format:, **_options)
+      validate_conversion_params(source, source_format, target, target_format)
+
+      log_conversion_start(source, source_format, target, target_format)
+
+      begin
+        # Step 1: Read source file to model (deserialization)
+        source_document = read_document(source, source_format)
+
+        # Step 2: Transform model (model-to-model transformation)
+        target_document = @transformer.transform(
+          source: source_document,
+          source_format: source_format,
+          target_format: target_format
+        )
+
+        # Step 3: Write target model to file (serialization)
+        write_document(target_document, target, target_format)
+
+        # Create success result
+        ConversionResult.new(
+          source: source,
+          source_format: source_format,
+          target: target,
+          target_format: target_format,
+          success: true,
+          paragraphs_count: document_stats(target_document)[:paragraphs],
+          tables_count: document_stats(target_document)[:tables],
+          images_count: document_stats(target_document)[:images]
+        )
+      rescue StandardError => e
+        # Create failure result
+        ConversionResult.new(
+          source: source,
+          source_format: source_format,
+          target: target,
+          target_format: target_format,
+          success: false,
+          error: e.message
+        )
+      end
+    end
+
+    # Convert MHTML to DOCX with explicit declaration.
+    #
+    # Declarative method that clearly states the conversion operation.
+    #
+    # @param source [String, IO] MHTML source file or stream
+    # @param target [String] DOCX target file path
+    # @param options [Hash] Conversion options
+    # @return [ConversionResult] Result object
+    #
+    # @example Declarative MHTML to DOCX
+    #   result = converter.mhtml_to_docx(
+    #     source: "document.mhtml",
+    #     target: "document.docx"
+    #   )
+    def mhtml_to_docx(source:, target:, **)
+      convert(
+        source: source,
+        source_format: :mhtml,
+        target: target,
+        target_format: :docx,
+        **
+      )
+    end
+
+    # Convert DOCX to MHTML with explicit declaration.
+    #
+    # Declarative method that clearly states the conversion operation.
+    #
+    # @param source [String, IO] DOCX source file or stream
+    # @param target [String] MHTML target file path
+    # @param options [Hash] Conversion options
+    # @return [ConversionResult] Result object
+    #
+    # @example Declarative DOCX to MHTML
+    #   result = converter.docx_to_mhtml(
+    #     source: "document.docx",
+    #     target: "document.mhtml"
+    #   )
+    def docx_to_mhtml(source:, target:, **)
+      convert(
+        source: source,
+        source_format: :docx,
+        target: target,
+        target_format: :mhtml,
+        **
+      )
+    end
+
+    # Batch convert multiple files explicitly.
+    #
+    # @param sources [Array<String>] Array of source file paths
+    # @param source_format [Symbol] Source format for all files
+    # @param target_format [Symbol] Target format for all files
+    # @param target_dir [String] Directory for output files
+    # @return [Array<ConversionResult>] Array of results
+    #
+    # @example Batch conversion
+    #   results = converter.batch_convert(
+    #     sources: Dir.glob("*.mhtml"),
+    #     source_format: :mhtml,
+    #     target_format: :docx,
+    #     target_dir: "converted/"
+    #   )
+    #   results.each { |r| puts r }
+    def batch_convert(sources:, source_format:, target_format:, target_dir:)
+      # Ensure target directory exists
+      FileUtils.mkdir_p(target_dir)
+
+      sources.map do |source|
+        basename = File.basename(source, File.extname(source))
+        target = File.join(target_dir, "#{basename}.#{target_format}")
+
+        convert(
+          source: source,
+          source_format: source_format,
+          target: target,
+          target_format: target_format
+        )
+      end
+    end
+
+    # Result object for conversion operations.
+    #
+    # Explicitly reports what happened during conversion.
+    # No hidden state - all information is accessible.
+    class ConversionResult
+      attr_reader :source, :source_format, :target, :target_format,
+                  :success, :paragraphs_count, :tables_count, :images_count,
+                  :error
+
+      # Initialize conversion result
+      #
+      # @param attributes [Hash] Result attributes
+      def initialize(attributes)
+        @source = attributes[:source]
+        @source_format = attributes[:source_format]
+        @target = attributes[:target]
+        @target_format = attributes[:target_format]
+        @success = attributes[:success]
+        @paragraphs_count = attributes[:paragraphs_count] || 0
+        @tables_count = attributes[:tables_count] || 0
+        @images_count = attributes[:images_count] || 0
+        @error = attributes[:error]
+      end
+
+      # Check if conversion succeeded
+      #
+      # @return [Boolean] true if successful
+      def success?
+        @success
+      end
+
+      # Get human-readable result summary
+      #
+      # @return [String] Conversion summary
+      def to_s
+        if success?
+          "Conversion: #{source_format} → #{target_format} " \
+            "(#{paragraphs_count} paragraphs, #{tables_count} tables, " \
+            "#{images_count} images) - SUCCESS"
+        else
+          "Conversion: #{source_format} → #{target_format} - FAILED: #{error}"
+        end
+      end
+
+      # Get detailed result as hash
+      #
+      # @return [Hash] Result details
+      def to_h
+        {
+          source: source,
+          source_format: source_format,
+          target: target,
+          target_format: target_format,
+          success: success,
+          paragraphs_count: paragraphs_count,
+          tables_count: tables_count,
+          images_count: images_count,
+          error: error
+        }
+      end
+    end
+
+    private
+
+    # Read document from file using format-specific handler
+    #
+    # @param source [String, IO] Source file or stream
+    # @param format [Symbol] Format to read
+    # @return [Document] Loaded document
+    def read_document(source, format)
+      DocumentFactory.from_file(source, format: format)
+    end
+
+    # Write document to file using format-specific handler
+    #
+    # @param document [Document] Document to write
+    # @param target [String, IO] Target file or stream
+    # @param format [Symbol] Format to write
+    def write_document(document, target, format)
+      writer = DocumentWriter.new(document)
+      writer.save(target, format: format)
+    end
+
+    # Get document statistics (paragraphs, tables, images)
+    #
+    # @param document [Object] Document (OOXML or MHTML)
+    # @return [Hash] Statistics hash
+    def document_stats(document)
+      # Handle OOXML document
+      if document.respond_to?(:paragraphs)
+        return {
+          paragraphs: document.paragraphs.count,
+          tables: document.respond_to?(:tables) ? document.tables.count : 0,
+          images: document.respond_to?(:images) ? document.images.count : 0
+        }
+      end
+
+      # Handle MHTML document - estimate from HTML content
+      html = if document.respond_to?(:raw_html) && document.raw_html
+               document.raw_html
+             elsif document.respond_to?(:html_content) && document.html_content
+               document.html_content
+             end
+      if html
+        {
+          paragraphs: html.scan(/<p[\s>]/i).count,
+          tables: html.scan(/<table/i).count,
+          images: html.scan(/<img/i).count
+        }
+      else
+        { paragraphs: 0, tables: 0, images: 0 }
+      end
+    end
+
+    # Validate conversion parameters
+    #
+    # @param source [Object] Source parameter
+    # @param source_format [Symbol] Source format
+    # @param target [Object] Target parameter
+    # @param target_format [Symbol] Target format
+    # @raise [ArgumentError] if parameters are invalid
+    def validate_conversion_params(source, source_format, target, target_format)
+      raise ArgumentError, 'Source cannot be nil' if source.nil?
+      raise ArgumentError, 'Source format must be specified' if source_format.nil?
+      raise ArgumentError, 'Target cannot be nil' if target.nil?
+      raise ArgumentError, 'Target format must be specified' if target_format.nil?
+
+      # Validate formats are supported
+      supported = %i[docx docm dotx dotm mhtml]
+      unless supported.include?(source_format)
+        raise ArgumentError,
+              "Unsupported source format: #{source_format}. " \
+              "Supported: #{supported.join(', ')}"
+      end
+      return if supported.include?(target_format)
+
+      raise ArgumentError,
+            "Unsupported target format: #{target_format}. " \
+            "Supported: #{supported.join(', ')}"
+    end
+
+    # Log conversion start
+    #
+    # @param source [String, IO] Source file
+    # @param source_format [Symbol] Source format
+    # @param target [String, IO] Target file
+    # @param target_format [Symbol] Target format
+    def log_conversion_start(source, source_format, target, target_format)
+      return unless @logger
+
+      source_name = source.respond_to?(:path) ? source.path : source.to_s
+      target_name = target.respond_to?(:path) ? target.path : target.to_s
+
+      @logger.info(
+        "Converting #{source_name} (#{source_format}) → #{target_name} (#{target_format})"
+      )
+    end
+  end
+end

data/lib/uniword/format_detector.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Detects document format from file signatures and extensions.
+  #
+  # Responsibility: Identify document format using file magic numbers
+  # and fallback to extension-based detection. Follows Single Responsibility
+  # Principle - detection logic separated from other concerns.
+  #
+  # Detection strategy:
+  # 1. Check file signature (magic number)
+  # 2. Check MIME headers for MHTML
+  # 3. Fallback to file extension
+  #
+  # @example Detect format
+  #   detector = Uniword::FormatDetector.new
+  #   format = detector.detect("document.docx")
+  #   # => :docx
+  class FormatDetector
+    # ZIP file magic number (PK\x03\x04)
+    ZIP_SIGNATURE = [0x50, 0x4B, 0x03, 0x04].pack('C*').freeze
+
+    # MIME version header for MHTML
+    MIME_HEADER = 'MIME-Version:'
+
+    # Detect the format of a file or stream.
+    #
+    # @param path [String, IO, StringIO] The file path or stream
+    # @return [Symbol] The detected format (:docx, :mhtml)
+    # @raise [ArgumentError] if path is invalid
+    # @raise [ArgumentError] if format cannot be detected
+    #
+    # @example Detect DOCX
+    #   detector = FormatDetector.new
+    #   format = detector.detect("document.docx")
+    #   # => :docx
+    def detect(path)
+      # For streams, detect from content
+      return detect_stream_format(path) if path.is_a?(IO) || path.is_a?(StringIO)
+
+      validate_path(path)
+
+      # Try signature-based detection first
+      format = detect_by_signature(path)
+      return format if format
+
+      # Fallback to extension-based detection
+      detect_by_extension(path)
+    end
+
+    private
+
+    # Validate file path.
+    #
+    # @param path [String, IO, StringIO] The path or stream to validate
+    # @return [void]
+    # @raise [ArgumentError] if path is invalid
+    def validate_path(path)
+      raise ArgumentError, 'Path cannot be nil' if path.nil?
+
+      # Allow IO and StringIO objects
+      return if path.is_a?(IO) || path.is_a?(StringIO)
+
+      # For strings, validate as file path
+      raise ArgumentError, 'Path cannot be empty' if path.respond_to?(:empty?) && path.empty?
+      raise ArgumentError, "File not found: #{path}" unless File.exist?(path)
+      raise ArgumentError, "Path is a directory: #{path}" if File.directory?(path)
+    end
+
+    # Detect format from stream content
+    #
+    # @param stream [IO, StringIO] The stream
+    # @return [Symbol] The detected format
+    def detect_stream_format(stream)
+      # Read header bytes
+      original_pos = stream.pos
+      header = stream.read(512)
+      stream.seek(original_pos) # Reset position
+
+      return nil if header.nil? || header.empty?
+
+      # Check for ZIP signature (DOCX)
+      return :docx if header.start_with?(ZIP_SIGNATURE)
+
+      # Check for MIME header (MHTML)
+      return :mhtml if header.include?(MIME_HEADER)
+
+      # Default to DOCX for unknown streams
+      :docx
+    end
+
+    # Detect format by file signature (magic number).
+    #
+    # @param path [String] The file path
+    # @return [Symbol, nil] The detected format or nil if unknown
+    def detect_by_signature(path)
+      # Read first few bytes for signature check
+      header = File.open(path, 'rb') { |f| f.read(512) }
+      return nil if header.nil? || header.empty?
+
+      # Check for ZIP signature (DOCX)
+      return :docx if header.start_with?(ZIP_SIGNATURE)
+
+      # Check for MIME header (MHTML)
+      return :mhtml if header.include?(MIME_HEADER)
+
+      nil
+    end
+
+    # Detect format by file extension.
+    #
+    # @param path [String] The file path
+    # @return [Symbol] The detected format
+    # @raise [ArgumentError] if extension is not recognized
+    def detect_by_extension(path)
+      extension = File.extname(path).downcase
+
+      case extension
+      when '.docx'
+        :docx
+      when '.docm'
+        :docm
+      when '.dotx'
+        :dotx
+      when '.dotm'
+        :dotm
+      when '.thmx'
+        :thmx
+      when '.mhtml', '.mht'
+        :mhtml
+      when '.doc'
+        raise ArgumentError,
+              'Old Word format (.doc) is not supported. Please convert to .docx first. ' \
+              'Uniword supports: .docx, .docm, .dotx, .dotm, .mhtml, .mht'
+      else
+        raise ArgumentError,
+              "Unsupported file extension: #{extension}. " \
+              'Supported extensions: .docx, .docm, .dotx, .dotm, .thmx, .mhtml, .mht'
+      end
+    end
+  end
+end

data/lib/uniword/glossary/auto_text.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  module Glossary
+    # Auto text flag for document parts
+    #
+    # Generated from OOXML schema: glossary.yml
+    # Element: <g:auto_text>
+    class AutoText < Lutaml::Model::Serializable
+      include Uniword::Properties::BooleanElement
+
+      attribute :val, :string, default: nil
+      include Uniword::Properties::BooleanValSetter
+
+      xml do
+        element 'auto_text'
+        namespace Uniword::Ooxml::Namespaces::Glossary
+        map_attribute 'val', to: :val, render_nil: false, render_default: false
+      end
+    end
+  end
+end

data/lib/uniword/glossary/category_name.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  module Glossary
+    # Name of a category
+    #
+    # Generated from OOXML schema: glossary.yml
+    # Element: <g:category_name>
+    class CategoryName < Lutaml::Model::Serializable
+      attribute :val, :string
+
+      xml do
+        root 'name'
+        namespace Uniword::Ooxml::Namespaces::WordProcessingML
+
+        map_attribute 'val', to: :val
+      end
+    end
+  end
+end

data/lib/uniword/glossary/doc_part.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  module Glossary
+    # Individual glossary entry with properties and content
+    #
+    # Generated from OOXML schema: glossary.yml
+    # Element: <g:doc_part>
+    class DocPart < Lutaml::Model::Serializable
+      attribute :doc_part_pr, DocPartProperties
+      attribute :doc_part_body, DocPartBody
+
+      xml do
+        root 'docPart'
+        namespace Uniword::Ooxml::Namespaces::WordProcessingML
+        mixed_content
+
+        map_element 'docPartPr', to: :doc_part_pr, render_nil: false
+        map_element 'docPartBody', to: :doc_part_body, render_nil: false
+      end
+    end
+  end
+end

data/lib/uniword/glossary/doc_part_behavior.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  module Glossary
+    # Individual behavior specification
+    #
+    # Generated from OOXML schema: glossary.yml
+    # Element: <g:doc_part_behavior>
+    class DocPartBehavior < Lutaml::Model::Serializable
+      attribute :val, :string
+
+      xml do
+        root 'behavior'
+        namespace Uniword::Ooxml::Namespaces::WordProcessingML
+
+        map_attribute 'val', to: :val
+      end
+    end
+  end
+end