uniword 1.2.5 → 1.3.0

data/lib/uniword/cli/page_cli.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Uniword
+  # Page subcommands for Uniword CLI.
+  #
+  # Uniform page setup across a document — the CLI equivalent of Word's
+  # Layout dialog (size, orientation, margins).
+  class PageCLI < Thor
+    include CLIHelpers
+
+    desc "setup INPUT OUTPUT", "Apply page setup to every section"
+    long_desc <<~DESC
+      Apply uniform page setup — paper size, orientation, and margins —
+      to every section of a document, the CLI equivalent of Word's
+      Layout dialog.
+
+      Examples:
+        $ uniword page setup input.docx output.docx --size a4
+        $ uniword page setup input.docx output.docx --size a4 --orientation landscape
+        $ uniword page setup input.docx output.docx --margins 1in
+        $ uniword page setup input.docx output.docx --margins 2.5cm --margin-top 3cm
+    DESC
+    option :size, type: :string,
+                  desc: "Paper size: letter, legal, a4, a5, executive"
+    option :orientation, type: :string,
+                         desc: "portrait or landscape"
+    option :margins, type: :string,
+                     desc: "Uniform margin for all sides " \
+                           "(1in, 2.5cm, 25mm, 1440)"
+    option :margin_top, type: :string, desc: "Top margin override"
+    option :margin_right, type: :string, desc: "Right margin override"
+    option :margin_bottom, type: :string, desc: "Bottom margin override"
+    option :margin_left, type: :string, desc: "Left margin override"
+    option :verbose, aliases: "-v", desc: "Verbose output", type: :boolean,
+                     default: false
+    def setup(input_path, output_path)
+      opts = setup_options
+      unless opts
+        say "Error: specify at least one of --size, --orientation, " \
+            "--margins, --margin-top/right/bottom/left", :red
+        exit 1
+      end
+
+      say "Loading document #{input_path}...", :green if options[:verbose]
+
+      sections = apply_setup(input_path, output_path, opts)
+      say "Page setup applied to #{sections} section(s) in #{output_path}",
+          :green
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
+    private
+
+    def setup_options
+      map = base_setup_options.merge(margin_setup_options)
+      map unless map.values.all?(&:nil?)
+    end
+
+    def base_setup_options
+      {
+        size: options[:size], orientation: options[:orientation],
+        margins: options[:margins]
+      }
+    end
+
+    def margin_setup_options
+      {
+        top: options[:margin_top], right: options[:margin_right],
+        bottom: options[:margin_bottom], left: options[:margin_left]
+      }
+    end
+
+    def apply_setup(input_path, output_path, opts)
+      doc = load_document(input_path)
+      sections = doc.apply_page_setup(**opts)
+      doc.save(output_path)
+      sections
+    end
+  end
+end

data/lib/uniword/cli/styles_cli.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Uniword
+  # Styles subcommands for Uniword CLI.
+  #
+  # Inspect the styles inside a document — the CLI equivalent of Word's
+  # Styles pane.
+  class StylesCLI < Thor
+    include CLIHelpers
+
+    desc "list FILE", "List styles in a document"
+    long_desc <<~DESC
+      List all styles defined in a document with their type, base
+      style, and key formatting — the CLI equivalent of Word's Styles
+      pane.
+
+      Examples:
+        $ uniword styles list report.docx
+        $ uniword styles list report.docx --type paragraph
+        $ uniword styles list report.docx --verbose
+    DESC
+    option :type, type: :string,
+                  desc: "Filter by type: paragraph, character, table, numbering"
+    option :verbose, aliases: "-v", desc: "Show formatting details",
+                     type: :boolean, default: false
+    def list(path)
+      styles = gather_styles(path)
+      if styles.empty?
+        say "No styles found.", :yellow
+        return
+      end
+
+      say "Styles in #{File.basename(path)} (#{styles.size}):", :green
+      styles.each { |style| print_style(style) }
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
+    desc "remove FILE OUTPUT", "Remove styles from a document"
+    long_desc <<~DESC
+      Remove styles from a document: one style with --id, or every
+      style that no content references with --unused (Word's Styles-pane
+      decluttering as a one-shot command). Default styles are kept.
+
+      Examples:
+        $ uniword styles remove input.docx output.docx --id ObsoleteStyle
+        $ uniword styles remove input.docx output.docx --unused
+        $ uniword styles remove input.docx output.docx --unused --dry-run
+    DESC
+    option :id, type: :string, desc: "Style id to remove"
+    option :unused, type: :boolean, default: false,
+                    desc: "Remove all unreferenced styles"
+    option :dry_run, type: :boolean, default: false,
+                     desc: "List what would be removed, without saving"
+    option :verbose, aliases: "-v", desc: "Verbose output",
+                     type: :boolean, default: false
+    def remove(input_path, output_path)
+      doc = load_document(input_path)
+      removed = run_removal(doc)
+      report_removal(doc, removed, output_path)
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
+    desc "rename FILE OUTPUT", "Rename a style's display name"
+    long_desc <<~DESC
+      Rename a style's display name (w:name) — Word's style rename.
+      References target the styleId, so renamed styles stay linked from
+      all content. Identify the style by --id (w:styleId) or --from
+      (current display name).
+
+      Examples:
+        $ uniword styles rename input.docx output.docx --id Heading1 --name "Chapter Title"
+        $ uniword styles rename input.docx output.docx --from "Old Name" --name "New Name"
+    DESC
+    option :id, type: :string, desc: "Style id (w:styleId) to rename"
+    option :from, type: :string, desc: "Current display name of the style"
+    option :name, type: :string, required: true, desc: "New display name"
+    option :verbose, aliases: "-v", desc: "Verbose output",
+                     type: :boolean, default: false
+    def rename(input_path, output_path)
+      identifier = rename_identifier
+      doc = load_document(input_path)
+      perform_rename(doc, identifier, output_path)
+    rescue Uniword::Error, StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
+    private
+
+    def rename_identifier
+      identifier = options[:id] || options[:from]
+      return identifier if identifier
+
+      say "Error: specify --id or --from to identify the style", :red
+      exit 1
+    end
+
+    def perform_rename(doc, identifier, output_path)
+      unless doc.rename_style(identifier, options[:name])
+        say "Style '#{identifier}' not found", :yellow
+        exit 1
+      end
+
+      doc.save(output_path)
+      say "Renamed style '#{identifier}' to '#{options[:name]}' " \
+          "in #{output_path}", :green
+    end
+
+    def run_removal(doc)
+      cleanup = Wordprocessingml::StyleCleanup.new(doc)
+      removal_error unless options[:unused] || options[:id]
+
+      removed_ids(cleanup)
+    end
+
+    def removed_ids(cleanup)
+      if options[:unused]
+        options[:dry_run] ? cleanup.unused_ids : cleanup.remove_unused
+      else
+        [options[:id]].select { |id| options[:dry_run] || cleanup.remove?(id) }
+      end
+    end
+
+    def removal_error
+      say "Error: specify --id or --unused", :red
+      exit 1
+    end
+
+    def report_removal(doc, removed, output_path)
+      if removed.empty?
+        say "No styles removed.", :yellow
+        return
+      end
+
+      verb = options[:dry_run] ? "Would remove" : "Removed"
+      say "#{verb} #{removed.size} style(s): #{removed.join(', ')}", :green
+      return if options[:dry_run]
+
+      doc.save(output_path)
+      say "Saved to #{output_path}", :green
+    end
+
+    def gather_styles(path)
+      doc = load_document(path)
+      filter_type(doc.styles_configuration.styles || [])
+    end
+
+    def filter_type(styles)
+      return styles unless options[:type]
+
+      styles.select { |s| s.type == options[:type] }
+    end
+
+    def print_style(style)
+      base = style.basedOn&.val || "-"
+      line = format("  %-24<id>s %-10<type>s base: %<base>s",
+                    id: style.styleId, type: style.type, base: base)
+      line += "  [#{style_details(style)}]" if options[:verbose]
+      say line
+    end
+
+    def style_details(style)
+      (name_detail(style) + font_details(style) + format_details(style))
+        .join(", ")
+    end
+
+    def name_detail(style)
+      style.name&.val ? ["name=#{style.name.val}"] : []
+    end
+
+    def font_details(style)
+      rpr = style.rPr
+      return [] unless rpr
+
+      [font_name(rpr), font_size(rpr)].compact
+    end
+
+    def font_name(rpr)
+      rpr.fonts&.ascii
+    end
+
+    def font_size(rpr)
+      size = rpr.size&.value
+      "#{size.to_i / 2.0}pt" if size
+    end
+
+    def format_details(style)
+      rpr = style.rPr
+      return [] unless rpr
+
+      flags = []
+      flags << "bold" if rpr.bold&.val
+      flags << "italic" if rpr.italic&.val
+      flags
+    end
+  end
+end

data/lib/uniword/cli/theme_cli.rb

@@ -147,6 +147,46 @@ module Uniword
       handle_error(e, verbose: options[:verbose])
     end
 
+    desc "fonts INPUT OUTPUT", "Apply a bundled font scheme to a document"
+    long_desc <<~DESC
+      Replace the document theme's font scheme (major/minor fonts) while
+      keeping colors and formats — the equivalent of Word's Design →
+      Fonts gallery. Use --list to see available font schemes.
+
+      Examples:
+        $ uniword theme fonts input.docx output.docx --name carlito_sans
+        $ uniword theme fonts --list
+    DESC
+    option :name, type: :string,
+                  desc: "Bundled font scheme name (e.g., carlito_sans)"
+    option :list, type: :boolean, default: false,
+                  desc: "List available bundled font schemes"
+    option :verbose, aliases: "-v", desc: "Verbose output", type: :boolean,
+                     default: false
+    def fonts(*args)
+      run_scheme_command(:fonts, args)
+    end
+
+    desc "colors INPUT OUTPUT", "Apply a bundled color scheme to a document"
+    long_desc <<~DESC
+      Replace the document theme's color scheme while keeping fonts and
+      formats — the equivalent of Word's Design → Colors gallery. Use
+      --list to see available color schemes.
+
+      Examples:
+        $ uniword theme colors input.docx output.docx --name emerald
+        $ uniword theme colors --list
+    DESC
+    option :name, type: :string,
+                  desc: "Bundled color scheme name (e.g., emerald)"
+    option :list, type: :boolean, default: false,
+                  desc: "List available bundled color schemes"
+    option :verbose, aliases: "-v", desc: "Verbose output", type: :boolean,
+                     default: false
+    def colors(*args)
+      run_scheme_command(:colors, args)
+    end
+
     desc "auto INPUT OUTPUT", "Auto-transition MS theme to Uniword equivalent"
     long_desc <<~DESC
       Detect the Microsoft Word theme in a document and automatically
@@ -192,8 +232,56 @@ module Uniword
       handle_error(e, verbose: options[:verbose])
     end
 
+    # Scheme-switching command configuration: loader, document method,
+    # and output label per command kind.
+    SCHEME_COMMANDS = {
+      fonts: {
+        loader: Resource::FontSchemeLoader,
+        doc_method: :apply_font_scheme,
+        label: "Font scheme",
+      },
+      colors: {
+        loader: Resource::ColorSchemeLoader,
+        doc_method: :apply_color_scheme,
+        label: "Color scheme",
+      },
+    }.freeze
+
     private
 
+    def run_scheme_command(kind, args)
+      config = SCHEME_COMMANDS.fetch(kind)
+      if options[:list]
+        config[:loader].available_schemes.each { |s| say s }
+        return
+      end
+
+      require_name!(:name, config[:loader])
+      apply_scheme_to_file(config, args)
+    rescue Uniword::Error => e
+      handle_error(e)
+    rescue StandardError => e
+      handle_error(e, verbose: options[:verbose])
+    end
+
+    def apply_scheme_to_file(config, (input_path, output_path))
+      say "Loading document #{input_path}...", :green if options[:verbose]
+
+      doc = load_document(input_path)
+      doc.method(config[:doc_method]).call(options[:name])
+      doc.save(output_path)
+      say "#{config[:label]} '#{options[:name]}' applied to #{output_path}",
+          :green
+    end
+
+    def require_name!(key, loader)
+      return if options[key]
+
+      say "Error: specify --name for a bundled scheme " \
+          "(available: #{loader.available_schemes.join(', ')})", :red
+      exit 1
+    end
+
     def apply_theme_to(doc)
       if options[:name]
         if options[:verbose]

data/lib/uniword/cli/toc_cli.rb

@@ -68,6 +68,9 @@ module Uniword
                       type: :numeric, default: 0
     option :max_level, desc: "Maximum heading level (1-6)", type: :numeric,
                        default: 3
+    option :update_fields, type: :boolean, default: true,
+                           desc: "Set w:updateFields so Word " \
+                                 "refreshes fields on open (default: true)"
     option :verbose, aliases: "-v", desc: "Show verbose output",
                      type: :boolean, default: false
     def insert(path)
@@ -84,7 +87,7 @@ module Uniword
                        position: options[:position],
                        max_level: options[:max_level])
 
-      doc.save(options[:output])
+      save_with_field_updates(doc, options[:output])
 
       say "TOC inserted with #{entries.count} entries at " \
           "position #{options[:position]}.", :green
@@ -109,6 +112,9 @@ module Uniword
                     type: :string
     option :max_level, desc: "Maximum heading level (1-6)", type: :numeric,
                        default: 6
+    option :update_fields, type: :boolean, default: true,
+                           desc: "Set w:updateFields so Word " \
+                                 "refreshes fields on open (default: true)"
     option :verbose, aliases: "-v", desc: "Show verbose output",
                      type: :boolean, default: false
     def update(path)
@@ -121,7 +127,7 @@ module Uniword
         return
       end
 
-      doc.save(options[:output])
+      save_with_field_updates(doc, options[:output])
 
       say "TOC updated with #{entries.count} entries.", :green
       say "Saved to: #{options[:output]}", :green
@@ -133,6 +139,20 @@ module Uniword
 
     private
 
+    # Set w:updateFields (unless disabled) and save the document.
+    def save_with_field_updates(doc, output)
+      enable_field_updates(doc) if options[:update_fields]
+      doc.save(output)
+    end
+
+    # Set w:updateFields so Word refreshes all fields (TOC, page
+    # numbers, references) when the document is opened. Word may show a
+    # one-time prompt about updating fields.
+    def enable_field_updates(doc)
+      doc.settings ||= Wordprocessingml::Settings.new
+      doc.settings.update_fields = Wordprocessingml::UpdateFields.new
+    end
+
     # Display TOC entries in terminal format.
     #
     # @param entries [Array<Uniword::Toc::TocEntry>] Entries to display

data/lib/uniword/comment.rb

@@ -19,19 +19,6 @@ module Uniword
   # @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
 
@@ -48,6 +35,19 @@ module Uniword
     attribute :paragraphs, Uniword::Wordprocessingml::Paragraph, collection: true,
                                                                  initialize_empty: true
 
+    # 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
+
     # Initialize a new comment
     #
     # @param attributes [Hash] Comment attributes
@@ -129,9 +129,14 @@ module Uniword
 
     # Generate a unique comment ID
     #
-    # @return [String] A unique comment ID
+    # OOXML w:id is ST_DecimalNumber (a 32-bit integer), so the fallback
+    # ID must be decimal digits only; CommentsPart#add_comment reassigns
+    # the ID when it collides inside the part, so time+random precision
+    # is sufficient here.
+    #
+    # @return [String] A unique decimal comment ID
     def generate_comment_id
-      "#{Time.now.to_i}_#{rand(10_000)}"
+      "#{Time.now.strftime('%H%M%S')}#{format('%03d', rand(1000))}".to_i.to_s
     end
 
     # Format date for OOXML

data/lib/uniword/comment_range.rb

@@ -27,6 +27,9 @@ module Uniword
   #
   # @see Comment For the comment content
   class CommentRange < Element
+    # Comment ID this range marker refers to
+    attribute :comment_id, :string
+
     # OOXML namespace configuration
     xml do
       element "commentRangeStart"
@@ -35,9 +38,6 @@ module Uniword
       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
 

data/lib/uniword/comments_part.rb

@@ -22,6 +22,11 @@ module Uniword
   #
   # @see Comment For individual comment structure
   class CommentsPart < Lutaml::Model::Serializable
+    include Enumerable
+
+    # Collection of all comments
+    attribute :comments, Comment, collection: true, initialize_empty: true
+
     # OOXML namespace configuration for comments
     xml do
       element "comments"
@@ -30,19 +35,12 @@ module Uniword
       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
     #
+    # Assigns the next sequential decimal ID when the comment has no ID
+    # yet or its ID collides with one already in the collection; explicit
+    # unique IDs are preserved.
+    #
     # @param comment [Comment] The comment to add
     # @return [Comment] The added comment with assigned ID
     def add_comment(comment)
@@ -51,9 +49,7 @@ module Uniword
               "comment must be a Comment instance"
       end
 
-      # Assign sequential ID if not already set
-      comment.comment_id = next_comment_id unless comment.comment_id && !comment.comment_id.empty?
-
+      comment.comment_id = next_comment_id if assign_id?(comment)
       comments << comment
       comment
     end
@@ -91,6 +87,29 @@ module Uniword
       comments.size
     end
 
+    # Get the number of comments (Array compatibility)
+    #
+    # @return [Integer] The count of comments
+    def size
+      comments.size
+    end
+
+    # Iterate over the comments (Array compatibility)
+    #
+    # @yield [Comment] Each comment in insertion order
+    # @return [Enumerator, Array<Comment>]
+    def each(&block)
+      comments.each(&block)
+    end
+
+    # Array-style access to comments (Array compatibility)
+    #
+    # @param index [Integer] Position in the collection
+    # @return [Comment, nil] The comment at the position
+    def [](index)
+      comments[index]
+    end
+
     # Check if there are any comments
     #
     # @return [Boolean] true if empty
@@ -110,7 +129,6 @@ module Uniword
     # @return [void]
     def clear
       comments.clear
-      @comment_counter = 0
     end
 
     # Provide detailed inspection for debugging
@@ -122,13 +140,27 @@ module Uniword
 
     private
 
-    # Generate next sequential comment ID
+    # Whether the comment needs an ID assigned by the collection: it has
+    # none, or another comment in the collection already carries it.
+    #
+    # @param comment [Comment] The comment being added
+    # @return [Boolean] true when an ID must be assigned
+    def assign_id?(comment)
+      id = comment.comment_id.to_s
+      id.empty? || !find_comment(id).nil?
+    end
+
+    # Generate the next sequential comment ID
+    #
+    # Decimal IDs already in the collection (loaded or assigned) set the
+    # high-water mark, so assigned IDs never collide with existing ones.
     #
     # @return [String] The next comment ID
     def next_comment_id
-      @comment_counter ||= 0
-      @comment_counter += 1
-      @comment_counter.to_s
+      max = comments.filter_map do |c|
+        Integer(c.comment_id, exception: false)
+      end.max
+      ((max || 0) + 1).to_s
     end
   end
 end

data/lib/uniword/configuration/configuration_loader.rb

@@ -3,7 +3,7 @@
 require "yaml"
 
 module Uniword
-  module Configuration
+  class Configuration
     # Loads and manages external configuration files.
     #
     # Responsibility: Load configuration from external YAML files.
@@ -65,12 +65,14 @@ module Uniword
         # 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 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')
+        #   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|