uniword 1.0.0

data/lib/uniword/column_configuration.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  # Represents a single column in a multi-column layout
+  #
+  # @attr [Integer] width Column width in twips
+  # @attr [Integer] space Space after this column in twips
+  class Column < Lutaml::Model::Serializable
+    attribute :width, :integer
+    attribute :space, :integer
+  end
+
+  # Represents column configuration for a section
+  #
+  # Columns allow text to flow in newspaper-style multi-column layouts.
+  #
+  # @example Two equal columns
+  #   cols = ColumnConfiguration.new(count: 2, equal_width: true, space: 720)
+  #
+  # @example Three unequal columns
+  #   cols = ColumnConfiguration.new(count: 3, equal_width: false)
+  #   cols.columns = [
+  #     Column.new(width: 2880, space: 360),
+  #     Column.new(width: 4320, space: 360),
+  #     Column.new(width: 2880, space: 0)
+  #   ]
+  #
+  # @attr [Integer] count Number of columns
+  # @attr [Boolean] equal_width Whether all columns have equal width
+  # @attr [Integer] space Default space between columns (for equal width)
+  # @attr [Boolean] separator Whether to show vertical separator line
+  # @attr [Array<Column>] columns Individual column definitions (for unequal)
+  class ColumnConfiguration < Lutaml::Model::Serializable
+    attribute :count, :integer, default: -> { 1 }
+    attribute :equal_width, :boolean, default: -> { true }
+    attribute :space, :integer, default: -> { 720 } # 0.5 inch
+    attribute :separator, :boolean, default: -> { false }
+    attribute :columns, Column, collection: true, initialize_empty: true
+
+    def initialize(**attributes)
+      super
+      validate_count
+      validate_columns
+    end
+
+    # Create equal-width columns configuration
+    #
+    # @param count [Integer] Number of columns
+    # @param space [Integer] Space between columns in twips
+    # @param separator [Boolean] Show separator line
+    # @return [ColumnConfiguration] New instance
+    def self.equal(count, space: 720, separator: false)
+      new(
+        count: count,
+        equal_width: true,
+        space: space,
+        separator: separator
+      )
+    end
+
+    # Create two-column layout
+    #
+    # @param space [Integer] Space between columns
+    # @param separator [Boolean] Show separator line
+    # @return [ColumnConfiguration] New instance
+    def self.two_columns(space: 720, separator: false)
+      equal(2, space: space, separator: separator)
+    end
+
+    # Create three-column layout
+    #
+    # @param space [Integer] Space between columns
+    # @param separator [Boolean] Show separator line
+    # @return [ColumnConfiguration] New instance
+    def self.three_columns(space: 720, separator: false)
+      equal(3, space: space, separator: separator)
+    end
+
+    # Check if using single column (no multi-column layout)
+    #
+    # @return [Boolean] true if single column
+    def single_column?
+      count == 1
+    end
+
+    # Check if using custom column widths
+    #
+    # @return [Boolean] true if custom widths
+    def custom_widths?
+      !equal_width && !columns.empty?
+    end
+
+    private
+
+    def validate_count
+      return unless count && count < 1
+
+      raise ArgumentError, "Column count must be at least 1, got: #{count}"
+    end
+
+    def validate_columns
+      return if equal_width || columns.empty?
+      return if columns.size == count
+
+      raise ArgumentError,
+            "Number of column definitions (#{columns.size}) must match count (#{count})"
+    end
+  end
+end

data/lib/uniword/comment.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Represents a comment in a Word document.
+  #
+  # Comments are annotations attached to content ranges, containing author
+  # information, timestamp, and comment text. They are part of Word's
+  # review and collaboration features.
+  #
+  # In OOXML, comments are stored in word/comments.xml and referenced
+  # via commentRangeStart, commentRangeEnd, and commentReference elements.
+  #
+  # @attr [String] author Comment author name
+  # @attr [String] text Comment text content
+  # @attr [Time] date Comment creation date/time
+  # @attr [String] initials Author initials (optional)
+  # @attr [Integer] comment_id Unique comment identifier
+  #
+  # @see CommentRange For comment range markers
+  # @see CommentsPart For comments collection
+  class Comment < Element
+    # OOXML namespace configuration for comments
+    xml do
+      element 'comment'
+      namespace Ooxml::Namespaces::WordProcessingML
+
+      map_attribute 'id', to: :comment_id
+      map_attribute 'author', to: :author
+      map_attribute 'date', to: :date
+      map_attribute 'initials', to: :initials
+
+      map_element 'p', to: :paragraphs
+    end
+
+    # Unique comment identifier (required in OOXML)
+    attribute :comment_id, :string
+
+    # Author name
+    attribute :author, :string
+
+    # Comment creation date/time
+    attribute :date, :string
+
+    # Author initials (optional)
+    attribute :initials, :string
+
+    # Comment content as paragraphs
+    attribute :paragraphs, Uniword::Wordprocessingml::Paragraph, collection: true,
+                                                                 initialize_empty: true
+
+    # Initialize a new comment
+    #
+    # @param attributes [Hash] Comment attributes
+    # @option attributes [String] :author Author name
+    # @option attributes [String] :text Comment text (creates paragraph)
+    # @option attributes [Time, String] :date Comment date
+    # @option attributes [String] :initials Author initials
+    # @option attributes [String] :comment_id Unique ID (auto-generated if not provided)
+    def initialize(attributes = {})
+      # Extract text before calling super to handle it specially
+      text_content = attributes.delete(:text)
+
+      super
+
+      # Auto-generate comment_id if not provided
+      @comment_id ||= generate_comment_id
+
+      # Set date to current time if not provided
+      @date ||= format_date(Time.now)
+
+      # Add text as a paragraph if provided
+      return unless text_content && !text_content.empty?
+
+      para = Uniword::Wordprocessingml::Paragraph.new
+      run = Uniword::Wordprocessingml::Run.new(text: text_content)
+      para.runs << run
+      paragraphs << para
+    end
+
+    # Accept a visitor for the visitor pattern
+    #
+    # @param visitor [Object] The visitor object
+    # @return [Object] The result of the visit operation
+    def accept(visitor)
+      visitor.visit_comment(self)
+    end
+
+    # Get the plain text content of this comment
+    # Concatenates text from all paragraphs
+    #
+    # @return [String] The combined text from all paragraphs
+    def text
+      paragraphs.map(&:text).join("\n")
+    end
+
+    # Check if comment is empty (has no paragraphs or all paragraphs are empty)
+    #
+    # @return [Boolean] true if empty
+    def empty?
+      paragraphs.empty? || paragraphs.all?(&:empty?)
+    end
+
+    # Provide detailed inspection for debugging
+    #
+    # @return [String] A readable representation of the comment
+    def inspect
+      text_preview = text[0..50]
+      text_preview += '...' if text.length > 50
+      "#<Uniword::Comment id=#{comment_id.inspect} author=#{author.inspect} text=#{text_preview.inspect}>"
+    end
+
+    # Check if comment is valid (has required attributes)
+    #
+    # @return [Boolean] true if valid
+    def valid?
+      required_attributes_valid?
+    end
+
+    protected
+
+    # Validate that comment has required attributes
+    #
+    # @return [Boolean] true if valid
+    def required_attributes_valid?
+      !author.nil? && !author.empty? && !comment_id.nil?
+    end
+
+    private
+
+    # Generate a unique comment ID
+    #
+    # @return [String] A unique comment ID
+    def generate_comment_id
+      "#{Time.now.to_i}_#{rand(10_000)}"
+    end
+
+    # Format date for OOXML
+    #
+    # @param time [Time] The time object
+    # @return [String] ISO 8601 formatted date string
+    def format_date(time)
+      return time if time.is_a?(String)
+
+      time.utc.iso8601
+    end
+  end
+end

data/lib/uniword/comment_range.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Represents a comment range marker in a Word document.
+  #
+  # Comments in Word documents are anchored to specific text ranges using
+  # commentRangeStart and commentRangeEnd markers. These markers define
+  # the beginning and end of the commented text.
+  #
+  # In OOXML:
+  # - <w:commentRangeStart> marks the start of a commented range
+  # - <w:commentRangeEnd> marks the end of a commented range
+  # - <w:commentReference> provides the actual link to the comment
+  #
+  # @example Create comment range markers
+  #   range_start = Uniword::CommentRange.new(
+  #     comment_id: "1",
+  #     marker_type: :start
+  #   )
+  #   range_end = Uniword::CommentRange.new(
+  #     comment_id: "1",
+  #     marker_type: :end
+  #   )
+  #
+  # @attr [String] comment_id The ID of the associated comment
+  # @attr [Symbol] marker_type Type of marker (:start, :end, :reference)
+  #
+  # @see Comment For the comment content
+  class CommentRange < Element
+    # OOXML namespace configuration
+    xml do
+      element 'commentRangeStart'
+      namespace Ooxml::Namespaces::WordProcessingML
+
+      map_attribute 'id', to: :comment_id
+    end
+
+    # Comment ID this range marker refers to
+    attribute :comment_id, :string
+
+    # Type of marker (:start, :end, :reference)
+    attr_accessor :marker_type
+
+    # Initialize a comment range marker
+    #
+    # @param attributes [Hash] Marker attributes
+    # @option attributes [String] :comment_id Comment ID (required)
+    # @option attributes [Symbol] :marker_type Marker type (:start, :end, :reference)
+    def initialize(attributes = {})
+      @marker_type = attributes.delete(:marker_type) || :start
+      super
+    end
+
+    # Accept a visitor for the visitor pattern
+    #
+    # @param visitor [Object] The visitor object
+    # @return [Object] The result of the visit operation
+    def accept(visitor)
+      visitor.visit_comment_range(self)
+    end
+
+    # Check if this is a start marker
+    #
+    # @return [Boolean] true if start marker
+    def start?
+      marker_type == :start
+    end
+
+    # Check if this is an end marker
+    #
+    # @return [Boolean] true if end marker
+    def end?
+      marker_type == :end
+    end
+
+    # Check if this is a reference marker
+    #
+    # @return [Boolean] true if reference marker
+    def reference?
+      marker_type == :reference
+    end
+
+    # Check if the comment range is valid
+    #
+    # @return [Boolean] true if valid, false otherwise
+    def valid?
+      required_attributes_valid?
+    end
+
+    # Get the XML element name based on marker type
+    #
+    # @return [String] The XML element name
+    def xml_element_name
+      case marker_type
+      when :start
+        'commentRangeStart'
+      when :end
+        'commentRangeEnd'
+      when :reference
+        'commentReference'
+      else
+        raise ArgumentError, "Invalid marker type: #{marker_type}"
+      end
+    end
+
+    # Provide detailed inspection for debugging
+    #
+    # @return [String] A readable representation of the comment range
+    def inspect
+      "#<Uniword::CommentRange type=#{marker_type.inspect} comment_id=#{comment_id.inspect}>"
+    end
+
+    protected
+
+    # Validate that comment range has required attributes
+    #
+    # @return [Boolean] true if valid
+    def required_attributes_valid?
+      !comment_id.nil? && !comment_id.empty? && !marker_type.nil?
+    end
+  end
+end

data/lib/uniword/comments_part.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Represents the comments part of a Word document (word/comments.xml).
+  #
+  # This class manages the collection of all comments in a document.
+  # In OOXML packages, comments are stored separately from the main
+  # document in word/comments.xml.
+  #
+  # The CommentsPart maintains a collection of Comment objects and
+  # handles serialization/deserialization to/from the comments.xml file.
+  #
+  # @example Create comments part
+  #   comments_part = Uniword::CommentsPart.new
+  #   comment = Uniword::Comment.new(
+  #     author: "John Doe",
+  #     text: "Please review"
+  #   )
+  #   comments_part.add_comment(comment)
+  #
+  # @attr [Array<Comment>] comments Collection of all comments
+  #
+  # @see Comment For individual comment structure
+  class CommentsPart < Lutaml::Model::Serializable
+    # OOXML namespace configuration for comments
+    xml do
+      element 'comments'
+      namespace Ooxml::Namespaces::WordProcessingML
+
+      map_element 'comment', to: :comments
+    end
+
+    # Collection of all comments
+    attribute :comments, Comment, collection: true, initialize_empty: true
+
+    # Initialize a new comments part
+    #
+    # @param attributes [Hash] Comments part attributes
+    def initialize(attributes = {})
+      super
+      @comment_counter = 0
+    end
+
+    # Add a comment to the collection
+    #
+    # @param comment [Comment] The comment to add
+    # @return [Comment] The added comment with assigned ID
+    def add_comment(comment)
+      raise ArgumentError, 'comment must be a Comment instance' unless comment.is_a?(Comment)
+
+      # Assign sequential ID if not already set
+      comment.comment_id = next_comment_id unless comment.comment_id && !comment.comment_id.empty?
+
+      comments << comment
+      comment
+    end
+
+    # Find a comment by ID
+    #
+    # @param comment_id [String] The comment ID to find
+    # @return [Comment, nil] The comment if found, nil otherwise
+    def find_comment(comment_id)
+      comments.find { |c| c.comment_id == comment_id.to_s }
+    end
+
+    # Remove a comment by ID
+    #
+    # @param comment_id [String] The comment ID to remove
+    # @return [Comment, nil] The removed comment if found, nil otherwise
+    def remove_comment(comment_id)
+      comment = find_comment(comment_id)
+      comments.delete(comment) if comment
+      comment
+    end
+
+    # Get all comments by a specific author
+    #
+    # @param author [String] The author name
+    # @return [Array<Comment>] Comments by the author
+    def comments_by_author(author)
+      comments.select { |c| c.author == author }
+    end
+
+    # Get the number of comments
+    #
+    # @return [Integer] The count of comments
+    def count
+      comments.size
+    end
+
+    # Check if there are any comments
+    #
+    # @return [Boolean] true if empty
+    def empty?
+      comments.empty?
+    end
+
+    # Get all unique authors
+    #
+    # @return [Array<String>] List of unique author names
+    def authors
+      comments.map(&:author).uniq.compact
+    end
+
+    # Clear all comments
+    #
+    # @return [void]
+    def clear
+      comments.clear
+      @comment_counter = 0
+    end
+
+    # Provide detailed inspection for debugging
+    #
+    # @return [String] A readable representation of the comments part
+    def inspect
+      "#<Uniword::CommentsPart count=#{count} authors=#{authors.count}>"
+    end
+
+    private
+
+    # Generate next sequential comment ID
+    #
+    # @return [String] The next comment ID
+    def next_comment_id
+      @comment_counter += 1
+      @comment_counter.to_s
+    end
+  end
+end

data/lib/uniword/configuration/configuration_loader.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Uniword
+  module Configuration
+    # Loads and manages external configuration files.
+    #
+    # Responsibility: Load configuration from external YAML files.
+    # Single Responsibility - only handles configuration loading.
+    #
+    # Follows "Configuration over Convention" principle - all configurable
+    # behavior is defined in external YAML files, not hardcoded in classes.
+    #
+    # @example Load transformation rules
+    #   config = ConfigurationLoader.load('transformation_rules')
+    #   property_mappings = config['property_mappings']
+    #
+    # @example Load with custom path
+    #   config = ConfigurationLoader.load_file('/custom/path/rules.yml')
+    class ConfigurationLoader
+      # Default configuration directory
+      CONFIG_DIR = File.expand_path('../../../config', __dir__)
+
+      class << self
+        # Load configuration from a named file in the config directory
+        #
+        # @param name [String] Configuration file name (without .yml)
+        # @return [Hash] Loaded configuration
+        # @raise [ConfigurationError] if file not found or invalid
+        #
+        # @example Load transformation rules
+        #   config = ConfigurationLoader.load('transformation_rules')
+        def load(name)
+          file_path = File.join(CONFIG_DIR, "#{name}.yml")
+          load_file(file_path)
+        end
+
+        # Load configuration from a specific file path
+        #
+        # @param path [String] Full path to configuration file
+        # @return [Hash] Loaded configuration
+        # @raise [ConfigurationError] if file not found or invalid
+        #
+        # @example Load from custom path
+        #   config = ConfigurationLoader.load_file('/custom/rules.yml')
+        def load_file(path)
+          validate_file_exists(path)
+
+          content = File.read(path)
+          parsed = YAML.safe_load(content, permitted_classes: [Symbol])
+
+          validate_configuration(parsed, path)
+
+          # Convert string keys to symbols for easier access
+          deep_symbolize_keys(parsed)
+        rescue Psych::SyntaxError => e
+          raise ConfigurationError,
+                "Invalid YAML in #{path}: #{e.message}"
+        rescue StandardError => e
+          raise ConfigurationError,
+                "Failed to load configuration from #{path}: #{e.message}"
+        end
+
+        # Get a configuration value with dot notation
+        #
+        # @param config [Hash] Configuration hash
+        # @param key_path [String] Dot-separated key path (e.g., 'format_defaults.docx.default_font')
+        # @param default [Object] Default value if key not found
+        # @return [Object] Configuration value or default
+        #
+        # @example Get nested value
+        #   font = ConfigurationLoader.get(config, 'format_defaults.docx.default_font')
+        def get(config, key_path, default = nil)
+          keys = key_path.split('.')
+          value = keys.reduce(config) do |hash, key|
+            return default unless hash.is_a?(Hash)
+
+            hash[key.to_sym] || hash[key.to_s]
+          end
+          value || default
+        end
+
+        # Merge two configuration hashes
+        #
+        # @param base [Hash] Base configuration
+        # @param override [Hash] Override configuration
+        # @return [Hash] Merged configuration
+        #
+        # @example Merge configurations
+        #   merged = ConfigurationLoader.merge(default_config, user_config)
+        def merge(base, override)
+          deep_merge(base.dup, override)
+        end
+
+        private
+
+        # Validate file exists
+        #
+        # @param path [String] File path
+        # @raise [ConfigurationError] if file doesn't exist
+        def validate_file_exists(path)
+          return if File.exist?(path)
+
+          raise ConfigurationError,
+                "Configuration file not found: #{path}"
+        end
+
+        # Validate configuration structure
+        #
+        # @param config [Object] Parsed configuration
+        # @param path [String] File path for error messages
+        # @raise [ConfigurationError] if configuration is invalid
+        def validate_configuration(config, path)
+          unless config.is_a?(Hash)
+            raise ConfigurationError,
+                  "Configuration must be a Hash, got #{config.class} in #{path}"
+          end
+
+          return unless config.empty?
+
+          raise ConfigurationError,
+                "Configuration cannot be empty in #{path}"
+        end
+
+        # Convert all string keys to symbols recursively
+        #
+        # @param obj [Object] Object to convert
+        # @return [Object] Object with symbolized keys
+        def deep_symbolize_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(key, value), result|
+              result[key.to_sym] = deep_symbolize_keys(value)
+            end
+          when Array
+            obj.map { |item| deep_symbolize_keys(item) }
+          else
+            obj
+          end
+        end
+
+        # Deep merge two hashes
+        #
+        # @param base [Hash] Base hash
+        # @param override [Hash] Override hash
+        # @return [Hash] Merged hash
+        def deep_merge(base, override)
+          override.each do |key, value|
+            base[key] = if base[key].is_a?(Hash) && value.is_a?(Hash)
+                          deep_merge(base[key], value)
+                        else
+                          value
+                        end
+          end
+          base
+        end
+      end
+    end
+
+    # Error raised when configuration loading fails
+    class ConfigurationError < Error
+      def initialize(message)
+        super("Configuration error: #{message}")
+      end
+    end
+  end
+end

data/lib/uniword/configuration.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Configuration
+    autoload :ConfigurationLoader, "#{__dir__}/configuration/configuration_loader"
+  end
+end

data/lib/uniword/content_types/default.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  module ContentTypes
+    # Default content type for file extension
+    #
+    # Generated from OOXML schema: content_types.yml
+    # Element: <ct:Default>
+    class Default < Lutaml::Model::Serializable
+      attribute :extension, :string
+      attribute :content_type, :string
+
+      xml do
+        element 'Default'
+        namespace Uniword::Ooxml::Namespaces::ContentTypes
+
+        map_attribute 'Extension', to: :extension
+        map_attribute 'ContentType', to: :content_type
+      end
+    end
+  end
+end