uniword 1.0.0 → 1.0.3

data/lib/uniword/builder/chart_builder.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'nokogiri'
-require 'securerandom'
+require "nokogiri"
+require "securerandom"
 
 module Uniword
   module Builder
@@ -27,12 +27,12 @@ module Uniword
     #     c.series 'Share', data: [45, 30, 25]
     #   end
     class ChartBuilder
-      CHART_NS = 'http://schemas.openxmlformats.org/drawingml/2006/chart'
+      CHART_NS = "http://schemas.openxmlformats.org/drawingml/2006/chart"
       CHART_REL_TYPE =
-        'http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart'
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart"
       CHART_CONTENT_TYPE =
-        'application/vnd.openxmlformats-officedocument.' \
-        'drawingml.chart+xml'
+        "application/vnd.openxmlformats-officedocument." \
+        "drawingml.chart+xml"
 
       attr_reader :chart_type, :title_text, :series_list
 
@@ -42,7 +42,7 @@ module Uniword
         @categories = []
         @series_list = []
         @show_legend = true
-        @legend_position = 'b'
+        @legend_position = "b"
         @width = 5_486_400  # default 6 inches in EMU
         @height = 3_200_400 # default ~3.5 inches in EMU
       end
@@ -60,10 +60,6 @@ module Uniword
         end
       end
 
-      # Set chart title
-      #
-      # @param text [String] Title text
-      # @return [self]
       def title(text)
         @title_text = text
         self
@@ -84,7 +80,7 @@ module Uniword
       # @param show [Boolean] Show legend (default true)
       # @param position [String] Position: 't', 'b', 'l', 'r', 'tr'
       # @return [self]
-      def legend(show: true, position: 'b')
+      def legend(show: true, position: "b")
         @show_legend = show
         @legend_position = position
         self
@@ -105,12 +101,12 @@ module Uniword
       #
       # @return [String] Chart XML
       def build_xml
-        builder = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
-          xml['c'].chartSpace('xmlns:c' => CHART_NS,
-                              'xmlns:a' =>
-                                'http://schemas.openxmlformats.org/drawingml/2006/main',
-                              'xmlns:r' =>
-                                'http://schemas.openxmlformats.org/officeDocument/2006/relationships') do
+        builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+          xml["c"].chartSpace("xmlns:c" => CHART_NS,
+                              "xmlns:a" =>
+                                "http://schemas.openxmlformats.org/drawingml/2006/main",
+                              "xmlns:r" =>
+                                "http://schemas.openxmlformats.org/officeDocument/2006/relationships") do
             build_chart_xml(xml)
           end
         end
@@ -130,7 +126,7 @@ module Uniword
 
         root.chart_parts[r_id] = {
           xml: build_xml,
-          target: target
+          target: target,
         }
 
         create_drawing(r_id)
@@ -140,169 +136,97 @@ module Uniword
 
       # Build the inner chart XML
       def build_chart_xml(xml)
-        xml['c'].chart do
-          # Title
+        xml["c"].chart do
           if @title_text
-            xml['c'].title do
-              xml['c'].tx do
-                xml['c'].rich do
-                  xml['a'].bodyPr
-                  xml['a'].lstStyle
-                  xml['a'].p do
-                    xml['a'].r do
-                      xml['a'].t(@title_text)
+            xml["c"].title do
+              xml["c"].tx do
+                xml["c"].rich do
+                  xml["a"].bodyPr
+                  xml["a"].lstStyle
+                  xml["a"].p do
+                    xml["a"].r do
+                      xml["a"].t(@title_text)
                     end
                   end
                 end
               end
-              xml['c'].overlay('val' => '0')
+              xml["c"].overlay("val" => "0")
             end
           end
 
-          xml['c'].autoTitleDeleted('val' => '0')
+          xml["c"].autoTitleDeleted("val" => "0")
 
-          # Plot area
-          xml['c'].plotArea do
+          xml["c"].plotArea do
             build_chart_type(xml)
 
-            # Category axis (for bar/line, not pie)
             unless @chart_type == :pie
-              xml['c'].catAx do
-                xml['c'].axId('val' => '10')
-                xml['c'].scaling do
-                  xml['c'].orientation('val' => 'minMax')
-                end
-                xml['c'].delete('val' => '0')
-                xml['c'].axPos('val' => 'b')
-                xml['c'].majorGridlines
-                xml['c'].numFmt('formatCode' => 'General',
-                                'sourceLinked' => '1')
-                xml['c'].tickLblPos('val' => 'nextTo')
-                xml['c'].crossAx('val' => '20')
-              end
-
-              # Value axis
-              xml['c'].valAx do
-                xml['c'].axId('val' => '20')
-                xml['c'].scaling do
-                  xml['c'].orientation('val' => 'minMax')
-                end
-                xml['c'].delete('val' => '0')
-                xml['c'].axPos('val' => 'l')
-                xml['c'].majorGridlines
-                xml['c'].numFmt('formatCode' => 'General',
-                                'sourceLinked' => '1')
-                xml['c'].tickLblPos('val' => 'nextTo')
-                xml['c'].crossAx('val' => '10')
-              end
+              build_axis(xml, "catAx", "10", "b", "20")
+              build_axis(xml, "valAx", "20", "l", "10")
             end
           end
 
-          # Legend
           if @show_legend
-            xml['c'].legend do
-              xml['c'].legendPos('val' => @legend_position)
-              xml['c'].overlay('val' => '0')
+            xml["c"].legend do
+              xml["c"].legendPos("val" => @legend_position)
+              xml["c"].overlay("val" => "0")
             end
           end
 
-          xml['c'].plotVisOnly('val' => '1')
+          xml["c"].plotVisOnly("val" => "1")
         end
       end
 
-      # Build the specific chart type element (bar, line, pie)
+      # Build the specific chart type element
       def build_chart_type(xml)
         case @chart_type
         when :bar
-          build_bar_chart(xml)
+          xml["c"].barChart do
+            xml["c"].barDir("val" => "col")
+            xml["c"].grouping("val" => "clustered")
+            xml["c"].varyColors("val" => "0")
+            build_all_series(xml)
+            xml["c"].axId("val" => "10")
+            xml["c"].axId("val" => "20")
+          end
         when :line
-          build_line_chart(xml)
+          xml["c"].lineChart do
+            xml["c"].grouping("val" => "standard")
+            xml["c"].varyColors("val" => "0")
+            build_all_series(xml)
+            xml["c"].axId("val" => "10")
+            xml["c"].axId("val" => "20")
+          end
         when :pie
-          build_pie_chart(xml)
-        end
-      end
-
-      # Build bar chart XML
-      def build_bar_chart(xml)
-        xml['c'].barChart do
-          xml['c'].barDir('val' => 'col')
-          xml['c'].grouping('val' => 'clustered')
-          xml['c'].varyColors('val' => '0')
-
-          @series_list.each_with_index do |s, i|
-            xml['c'].ser do
-              xml['c'].idx('val' => i)
-              xml['c'].order('val' => i)
-              xml['c'].tx do
-                xml['c'].strRef do
-                  xml['c'].f("Sheet1!$B$#{i + 1}")
-                  xml['c'].strCache do
-                    xml['c'].ptCount('val' => 1)
-                    xml['c'].pt('idx' => 0) { xml['c'].v(s[:name]) }
-                  end
-                end
-              end
-              build_categories(xml)
-              build_values(xml, s[:data])
-            end
+          xml["c"].pieChart do
+            xml["c"].varyColors("val" => "1")
+            build_all_series(xml)
           end
-
-          xml['c'].axId('val' => '10')
-          xml['c'].axId('val' => '20')
         end
       end
 
-      # Build line chart XML
-      def build_line_chart(xml)
-        xml['c'].lineChart do
-          xml['c'].grouping('val' => 'standard')
-          xml['c'].varyColors('val' => '0')
-
-          @series_list.each_with_index do |s, i|
-            xml['c'].ser do
-              xml['c'].idx('val' => i)
-              xml['c'].order('val' => i)
-              xml['c'].tx do
-                xml['c'].strRef do
-                  xml['c'].f("Sheet1!$B$#{i + 1}")
-                  xml['c'].strCache do
-                    xml['c'].ptCount('val' => 1)
-                    xml['c'].pt('idx' => 0) { xml['c'].v(s[:name]) }
-                  end
-                end
-              end
-              build_categories(xml)
-              build_values(xml, s[:data])
-            end
-          end
-
-          xml['c'].axId('val' => '10')
-          xml['c'].axId('val' => '20')
+      # Build all series XML blocks
+      def build_all_series(xml)
+        @series_list.each_with_index do |s, i|
+          build_series(xml, s, i)
         end
       end
 
-      # Build pie chart XML
-      def build_pie_chart(xml)
-        xml['c'].pieChart do
-          xml['c'].varyColors('val' => '1')
-
-          @series_list.each_with_index do |s, i|
-            xml['c'].ser do
-              xml['c'].idx('val' => i)
-              xml['c'].order('val' => i)
-              xml['c'].tx do
-                xml['c'].strRef do
-                  xml['c'].f("Sheet1!$B$#{i + 1}")
-                  xml['c'].strCache do
-                    xml['c'].ptCount('val' => 1)
-                    xml['c'].pt('idx' => 0) { xml['c'].v(s[:name]) }
-                  end
-                end
+      # Build a single series XML block
+      def build_series(xml, series, index)
+        xml["c"].ser do
+          xml["c"].idx("val" => index)
+          xml["c"].order("val" => index)
+          xml["c"].tx do
+            xml["c"].strRef do
+              xml["c"].f("Sheet1!$B$#{index + 1}")
+              xml["c"].strCache do
+                xml["c"].ptCount("val" => 1)
+                xml["c"].pt("idx" => 0) { xml["c"].v(series[:name]) }
               end
-              build_categories(xml)
-              build_values(xml, s[:data])
             end
           end
+          build_categories(xml)
+          build_values(xml, series[:data])
         end
       end
 
@@ -310,13 +234,13 @@ module Uniword
       def build_categories(xml)
         return if @categories.empty?
 
-        xml['c'].cat do
-          xml['c'].strRef do
-            xml['c'].f('Sheet1!$A$2:$A$100')
-            xml['c'].strCache do
-              xml['c'].ptCount('val' => @categories.size)
+        xml["c"].cat do
+          xml["c"].strRef do
+            xml["c"].f("Sheet1!$A$2:$A$100")
+            xml["c"].strCache do
+              xml["c"].ptCount("val" => @categories.size)
               @categories.each_with_index do |cat, idx|
-                xml['c'].pt('idx' => idx) { xml['c'].v(cat) }
+                xml["c"].pt("idx" => idx) { xml["c"].v(cat) }
               end
             end
           end
@@ -325,20 +249,37 @@ module Uniword
 
       # Build values data XML
       def build_values(xml, data)
-        xml['c'].val do
-          xml['c'].numRef do
-            xml['c'].f('Sheet1!$C$2:$C$100')
-            xml['c'].numCache do
-              xml['c'].formatCode('General')
-              xml['c'].ptCount('val' => data.size)
+        xml["c"].val do
+          xml["c"].numRef do
+            xml["c"].f("Sheet1!$C$2:$C$100")
+            xml["c"].numCache do
+              xml["c"].formatCode("General")
+              xml["c"].ptCount("val" => data.size)
               data.each_with_index do |val, idx|
-                xml['c'].pt('idx' => idx) { xml['c'].v(val.to_s) }
+                xml["c"].pt("idx" => idx) { xml["c"].v(val.to_s) }
               end
             end
           end
         end
       end
 
+      # Build a chart axis
+      def build_axis(xml, tag, id, position, cross_id)
+        xml["c"].send(tag) do
+          xml["c"].axId("val" => id)
+          xml["c"].scaling do
+            xml["c"].orientation("val" => "minMax")
+          end
+          xml["c"].delete("val" => "0")
+          xml["c"].axPos("val" => position)
+          xml["c"].majorGridlines
+          xml["c"].numFmt("formatCode" => "General",
+                          "sourceLinked" => "1")
+          xml["c"].tickLblPos("val" => "nextTo")
+          xml["c"].crossAx("val" => cross_id)
+        end
+      end
+
       # Create a Drawing element with chart reference
       def create_drawing(r_id)
         drawing = Wordprocessingml::Drawing.new
@@ -348,7 +289,7 @@ module Uniword
         inline.effect_extent = WpDrawing::EffectExtent.new
         inline.doc_properties = WpDrawing::DocProperties.new(
           id: SecureRandom.random_number(1_000_000_000),
-          name: "Chart #{SecureRandom.random_number(1_000_000)}"
+          name: "Chart #{SecureRandom.random_number(1_000_000)}",
         )
 
         graphic = Drawingml::Graphic.new

data/lib/uniword/builder/comment_builder.rb

@@ -16,7 +16,7 @@ module Uniword
           author: author,
           comment_id: comment_id,
           date: date,
-          initials: initials
+          initials: initials,
         )
       end
 

data/lib/uniword/builder/document_builder.rb

@@ -28,11 +28,13 @@ module Uniword
     #   doc.page_break
     #   doc.footer { |f| f << Builder.page_number_field }
     #   doc.save('report.docx')
-    class DocumentBuilder
-      attr_reader :model
+    class DocumentBuilder < BaseBuilder
+      def self.default_model_class
+        Wordprocessingml::DocumentRoot
+      end
 
       def initialize(model = nil)
-        @model = model || Wordprocessingml::DocumentRoot.new
+        super
         @bookmark_counter = 0
         @footnote_builder = FootnoteBuilder.new(self)
         @comment_counter = 0
@@ -119,7 +121,7 @@ module Uniword
       # @param type [String] Section break type ('nextPage', 'continuous', 'evenPage', 'oddPage')
       # @yield [SectionBuilder] Builder for section configuration
       # @return [SectionBuilder] The section builder
-      def section(type: 'nextPage', &block)
+      def section(type: "nextPage", &block)
         sec = SectionBuilder.new
         sec.type = type
         block.call(sec) if block_given?
@@ -132,7 +134,7 @@ module Uniword
       # @param type [String] Header type ('default', 'first', 'even')
       # @yield [HeaderFooterBuilder] Builder for header content
       # @return [HeaderFooterBuilder] The header/footer builder
-      def header(type: 'default', &block)
+      def header(type: "default", &block)
         hf = HeaderFooterBuilder.new(:header, type: type)
         block.call(hf) if block_given?
         (@model.headers ||= {})[type] = hf.build
@@ -144,7 +146,7 @@ module Uniword
       # @param type [String] Footer type ('default', 'first', 'even')
       # @yield [HeaderFooterBuilder] Builder for footer content
       # @return [HeaderFooterBuilder] The header/footer builder
-      def footer(type: 'default', &block)
+      def footer(type: "default", &block)
         hf = HeaderFooterBuilder.new(:footer, type: type)
         block.call(hf) if block_given?
         (@model.footers ||= {})[type] = hf.build
@@ -156,7 +158,7 @@ module Uniword
       # @param title [String] TOC title (default 'Table of Contents')
       # @param styles [Array<String>, nil] Heading styles to include
       # @return [self]
-      def toc(title: 'Table of Contents', styles: nil)
+      def toc(title: "Table of Contents", styles: nil)
         TocBuilder.build(title: title, styles: styles).each do |para|
           @model.body.paragraphs << para
         end
@@ -211,8 +213,6 @@ module Uniword
 
       # Create a footnote and return a Run with a footnoteReference.
       #
-      # The returned Run can be appended to a paragraph using <<.
-      #
       # @param text [String] Footnote text
       # @yield [ParagraphBuilder] Builder for rich footnote content
       # @return [Wordprocessingml::Run] Run with footnote reference
@@ -247,71 +247,43 @@ module Uniword
       # @param base_on [String] Base style (default 'Normal')
       # @yield [StyleBuilder] Builder for style configuration
       # @return [StyleBuilder] The style builder
-      def define_style(name, base_on: 'Normal', &block)
+      def define_style(name, base_on: "Normal", &block)
         style = StyleBuilder.new(name, base_on: base_on)
         block.call(style) if block_given?
         @model.styles_configuration.add_style(style.build)
         style
       end
 
-      # Set document title
-      #
-      # @param value [String] Title
-      # @return [self]
       def title(value)
         @model.core_properties.title = value
         self
       end
 
-      # Set document author (creator)
-      #
-      # @param value [String] Author name
-      # @return [self]
       def author(value)
         @model.core_properties.creator = value
         self
       end
 
-      # Set document description
-      #
-      # @param value [String] Description
-      # @return [self]
       def description(value)
         @model.core_properties.description = value
         self
       end
 
-      # Set document subject
-      #
-      # @param value [String] Subject
-      # @return [self]
       def subject(value)
         @model.core_properties.subject = value
         self
       end
 
-      # Set document keywords
-      #
-      # @param value [String] Keywords
-      # @return [self]
       def keywords(value)
         @model.core_properties.keywords = value
         self
       end
 
-      # Set document creation date
-      #
-      # @param value [Time, String] Creation date
-      # @return [self]
       def created(value)
         @model.core_properties.created = value
         self
       end
 
-      # Set document modification date
-      #
-      # @param value [Time, String] Modification date
-      # @return [self]
       def modified(value)
         @model.core_properties.modified = value
         self
@@ -333,7 +305,7 @@ module Uniword
       # @param color [String] Border color (default 'auto')
       # @param size [Integer] Border size in eighths of a point (default 6)
       # @return [self]
-      def horizontal_rule(style: 'single', color: 'auto', size: 6)
+      def horizontal_rule(style: "single", color: "auto", size: 6)
         para = ParagraphBuilder.new
         para.borders(
           bottom: { style: style, color: color, size: size }
@@ -384,9 +356,6 @@ module Uniword
 
       # Add a watermark to the document header
       #
-      # Creates a VML text shape in the default header that renders
-      # as a semi-transparent watermark across the page.
-      #
       # @param text [String, nil] Watermark text (nil to clear)
       # @param font [String] Font name (default 'Calibri')
       # @param size [Integer] Font size in points (default 60)
@@ -394,10 +363,10 @@ module Uniword
       # @param opacity [String] Opacity '0.0' to '1.0' (default '0.3')
       # @param angle [Integer] Rotation angle in degrees (default -45)
       # @return [self]
-      def watermark(text, font: 'Calibri', size: 60, color: nil,
-                    opacity: '0.3', angle: -45)
+      def watermark(text, font: "Calibri", size: 60, color: nil,
+                    opacity: "0.3", angle: -45)
         if text.nil?
-          (@model.headers ||= {}).delete('default')
+          (@model.headers ||= {}).delete("default")
           return self
         end
 
@@ -408,15 +377,12 @@ module Uniword
 
         header = Wordprocessingml::Header.new
         header.paragraphs << para
-        (@model.headers ||= {})['default'] = header
+        (@model.headers ||= {})["default"] = header
         self
       end
 
       # Create a comment and store it in the document's comments collection.
       #
-      # The comment is created using CommentBuilder and stored in
-      # document.comments for later serialization.
-      #
       # @param author [String] Comment author name
       # @param text [String, nil] Comment text
       # @param initials [String, nil] Author initials
@@ -457,7 +423,7 @@ module Uniword
       # @param style [String] Citation style (default 'APA')
       # @yield [BibliographyBuilder] Builder for source configuration
       # @return [BibliographyBuilder] The bibliography builder
-      def bibliography(style: 'APA', &block)
+      def bibliography(style: "APA", &block)
         bib = BibliographyBuilder.new(style: style)
         block.call(bib) if block_given?
         bib.attach(self)
@@ -516,7 +482,7 @@ module Uniword
       #
       # @param format [String] Date format (default 'M/d/yyyy')
       # @return [self]
-      def date_field(format: 'M/d/yyyy')
+      def date_field(format: "M/d/yyyy")
         @model.body.paragraphs << Builder.date_field(format: format)
         self
       end
@@ -525,18 +491,11 @@ module Uniword
       #
       # @param format [String] Time format (default 'h:mm:ss am/pm')
       # @return [self]
-      def time_field(format: 'h:mm:ss am/pm')
+      def time_field(format: "h:mm:ss am/pm")
         @model.body.paragraphs << Builder.time_field(format: format)
         self
       end
 
-      # Return the underlying DocumentRoot model
-      #
-      # @return [Wordprocessingml::DocumentRoot]
-      def build
-        @model
-      end
-
       # Save document to file
       #
       # @param path [String] Output file path

data/lib/uniword/builder/footnote_builder.rb

@@ -75,7 +75,7 @@ module Uniword
       end
 
       def create_footnote_entry(id, text, &block)
-        entry = Wordprocessingml::Footnote.new(id: id.to_s, type: 'normal')
+        entry = Wordprocessingml::Footnote.new(id: id.to_s, type: "normal")
         para = ParagraphBuilder.new
         if block_given?
           block.call(para)
@@ -87,7 +87,7 @@ module Uniword
       end
 
       def create_endnote_entry(id, text, &block)
-        entry = Wordprocessingml::Endnote.new(id: id.to_s, type: 'normal')
+        entry = Wordprocessingml::Endnote.new(id: id.to_s, type: "normal")
         para = ParagraphBuilder.new
         if block_given?
           block.call(para)

data/lib/uniword/builder/has_borders.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Mixin for builders that support border configuration.
+    #
+    # Expects the including class to implement #ensure_properties
+    # returning the properties object that has a #borders accessor.
+    module HasBorders
+      def borders(**sides)
+        props = ensure_properties
+        props.borders ||= Properties::Borders.new
+        sides.each do |side, value|
+          border = if value.is_a?(Hash)
+                     Properties::Border.new(**value)
+                   else
+                     Properties::Border.new(color: value, style: "single",
+                                            size: 4)
+                   end
+          props.borders.send("#{side}=", border)
+        end
+        self
+      end
+    end
+  end
+end

data/lib/uniword/builder/has_shading.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Mixin for builders that support shading configuration.
+    #
+    # Expects the including class to implement #ensure_properties
+    # returning the properties object that has a #shading= setter.
+    module HasShading
+      def shading(fill:, color: nil, pattern: "clear")
+        props = ensure_properties
+        props.shading = Properties::Shading.new(
+          fill: fill, color: color, pattern: pattern,
+        )
+        self
+      end
+    end
+  end
+end