uniword 1.0.0

data/lib/uniword/builder/section_builder.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and configures SectionProperties objects.
+    #
+    # @example Configure page setup
+    #   doc.section do |s|
+    #     s.page_size(width: 12240, height: 15840)
+    #     s.margins(top: 1440, bottom: 1440, left: 1440, right: 1440)
+    #   end
+    #
+    # @example Configure section with page numbering
+    #   doc.section(type: 'nextPage') do |s|
+    #     s.page_size(orientation: 'landscape')
+    #     s.page_numbering(start: 1, format: 'lowerRoman')
+    #     s.margins(top: 720, bottom: 720)
+    #   end
+    class SectionBuilder
+      attr_reader :model
+
+      def initialize(model = nil)
+        @model = model || Wordprocessingml::SectionProperties.new
+      end
+
+      # Wrap an existing SectionProperties model
+      def self.from_model(model)
+        new(model)
+      end
+
+      # Set section break type
+      #
+      # @param value [String] 'nextPage', 'continuous', 'evenPage', 'oddPage'
+      # @return [self]
+      def type=(value)
+        @model.type = value
+        self
+      end
+
+      # Set page size
+      #
+      # @param width [Integer] Page width in twips (default US Letter: 12240)
+      # @param height [Integer] Page height in twips (default US Letter: 15840)
+      # @param orientation [String] 'portrait' or 'landscape'
+      # @return [self]
+      def page_size(width: 12_240, height: 15_840, orientation: 'portrait')
+        @model.page_size ||= Wordprocessingml::PageSize.new
+        @model.page_size.width = width
+        @model.page_size.height = height
+        @model.page_size.orientation = orientation
+        self
+      end
+
+      # Set page margins
+      #
+      # @param top [Integer] Top margin in twips (default 1440 = 1 inch)
+      # @param bottom [Integer] Bottom margin in twips
+      # @param left [Integer] Left margin in twips
+      # @param right [Integer] Right margin in twips
+      # @param header [Integer] Header distance from edge in twips
+      # @param footer [Integer] Footer distance from edge in twips
+      # @param gutter [Integer] Gutter margin in twips
+      # @return [self]
+      def margins(top: 1440, bottom: 1440, left: 1440, right: 1440,
+                  header: 720, footer: 720, gutter: 0)
+        @model.page_margins ||= Wordprocessingml::PageMargins.new
+        @model.page_margins.top = top
+        @model.page_margins.bottom = bottom
+        @model.page_margins.left = left
+        @model.page_margins.right = right
+        @model.page_margins.header = header
+        @model.page_margins.footer = footer
+        @model.page_margins.gutter = gutter
+        self
+      end
+
+      # Set number of columns
+      #
+      # @param count [Integer] Number of columns
+      # @param spacing [Integer] Space between columns in twips
+      # @return [self]
+      def columns(count: 1, spacing: 720)
+        @model.columns ||= Wordprocessingml::Columns.new
+        @model.columns.num = count
+        @model.columns.space = spacing
+        self
+      end
+
+      # Set page borders
+      #
+      # @param options [Hash] Border options
+      # @return [self]
+      def page_borders(**_options)
+        @model.page_borders ||= Wordprocessingml::PageBorders.new
+        self
+      end
+
+      # Set line numbering
+      #
+      # @param count_by [Integer] Line numbering interval
+      # @param start [Integer] Starting line number
+      # @param restart [String] Restart setting ('continuous', 'newPage', 'newSection')
+      # @return [self]
+      def line_numbering(count_by: 1, start: 1, restart: 'continuous')
+        @model.line_numbering ||= Wordprocessingml::LineNumbering.new
+        @model.line_numbering.count_by = count_by
+        @model.line_numbering.start = start
+        @model.line_numbering.restart = restart
+        self
+      end
+
+      # Set page numbering for this section
+      #
+      # @param start [Integer, nil] Starting page number
+      # @param format [String, nil] Number format ('decimal', 'lowerRoman', 'upperRoman')
+      # @return [self]
+      def page_numbering(start: nil, format: nil)
+        @model.page_numbering ||= Wordprocessingml::PageNumbering.new
+        @model.page_numbering.start = start if start
+        @model.page_numbering.format = format if format
+        self
+      end
+
+      # Configure a header for this section
+      #
+      # Creates a HeaderReference attached to the section properties.
+      # The header content is built using a HeaderFooterBuilder.
+      #
+      # @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)
+        hf = HeaderFooterBuilder.new(:header, type: type)
+        block.call(hf) if block_given?
+
+        ref = Wordprocessingml::HeaderReference.new(
+          type: type, r_id: "rIdHdr#{type}"
+        )
+        @model.header_references << ref
+        hf
+      end
+
+      # Configure a footer for this section
+      #
+      # Creates a FooterReference attached to the section properties.
+      # The footer content is built using a HeaderFooterBuilder.
+      #
+      # @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)
+        hf = HeaderFooterBuilder.new(:footer, type: type)
+        block.call(hf) if block_given?
+
+        ref = Wordprocessingml::FooterReference.new(
+          type: type, r_id: "rIdFtr#{type}"
+        )
+        @model.footer_references << ref
+        hf
+      end
+
+      # Return the underlying SectionProperties model
+      #
+      # @return [Wordprocessingml::SectionProperties]
+      def build
+        @model
+      end
+    end
+  end
+end

data/lib/uniword/builder/style_builder.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and configures Style objects.
+    #
+    # @example Define a heading style
+    #   doc.define_style('MyHeading', base_on: 'Heading1') do |s|
+    #     s.font_size(28)
+    #     s.bold(true)
+    #     s.color('2E74B5')
+    #   end
+    class StyleBuilder
+      attr_reader :model
+
+      def initialize(name, base_on: 'Normal')
+        @model = Wordprocessingml::Style.new
+        @model.styleId = name.tr(' ', '')
+        @model.name = Wordprocessingml::StyleName.new(val: name)
+        @model.basedOn = Wordprocessingml::BasedOn.new(val: base_on)
+      end
+
+      # Wrap an existing Style model
+      def self.from_model(model)
+        base = model.basedOn&.val || 'Normal'
+        new(model.name&.val || model.name.to_s, base_on: base)
+      end
+
+      # Set style type
+      #
+      # @param value [String] 'paragraph' or 'character'
+      # @return [self]
+      def type=(value)
+        @model.type = value
+        self
+      end
+
+      # Set font size in points
+      #
+      # @param points [Integer] Font size in points
+      # @return [self]
+      def font_size(points)
+        ensure_run_props
+        @model.rPr.size = Properties::FontSize.new(value: points.to_i * 2)
+        self
+      end
+
+      # Set bold
+      #
+      # @param value [Boolean] Bold state (default true)
+      # @return [self]
+      def bold(value = true)
+        ensure_run_props
+        @model.rPr.bold = Properties::Bold.new(value: value)
+        self
+      end
+
+      # Set italic
+      #
+      # @param value [Boolean] Italic state (default true)
+      # @return [self]
+      def italic(value = true)
+        ensure_run_props
+        @model.rPr.italic = Properties::Italic.new(value: value)
+        self
+      end
+
+      # Set font color
+      #
+      # @param value [String] Color as hex string
+      # @return [self]
+      def color(value)
+        ensure_run_props
+        @model.rPr.color = Properties::ColorValue.new(value: value)
+        self
+      end
+
+      # Set font name
+      #
+      # @param value [String] Font family
+      # @return [self]
+      def font(value)
+        ensure_run_props
+        @model.rPr.font = value
+        self
+      end
+
+      # Set paragraph alignment
+      #
+      # @param value [String] :left, :center, :right, :justify
+      # @return [self]
+      def align(value)
+        ensure_para_props
+        @model.pPr.alignment = value.to_s
+        self
+      end
+
+      # Set paragraph spacing
+      #
+      # @param before [Integer, nil] Spacing before in twips
+      # @param after [Integer, nil] Spacing after in twips
+      # @param line [Integer, nil] Line spacing in twips
+      # @return [self]
+      def spacing(before: nil, after: nil, line: nil)
+        ensure_para_props
+        @model.pPr.spacing ||= Properties::Spacing.new
+        @model.pPr.spacing.before = before if before
+        @model.pPr.spacing.after = after if after
+        @model.pPr.spacing.line = line if line
+        self
+      end
+
+      # Return the underlying Style model
+      def build
+        @model
+      end
+
+      private
+
+      def ensure_run_props
+        @model.rPr ||= Wordprocessingml::RunProperties.new
+      end
+
+      def ensure_para_props
+        @model.pPr ||= Wordprocessingml::ParagraphProperties.new
+      end
+    end
+  end
+end

data/lib/uniword/builder/table_builder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and configures Table objects.
+    #
+    # @example Create a table
+    #   doc.table do |t|
+    #     t.row do |r|
+    #       r.cell(text: 'Name')
+    #       r.cell(text: 'Value')
+    #     end
+    #   end
+    class TableBuilder
+      attr_reader :model
+
+      def initialize(model = nil)
+        @model = model || Wordprocessingml::Table.new
+      end
+
+      # Wrap an existing Table model
+      def self.from_model(model)
+        new(model)
+      end
+
+      # Create and add a row to the table
+      #
+      # @yield [TableRowBuilder] Builder for row configuration
+      # @return [TableRowBuilder] The row builder
+      def row(&block)
+        r = TableRowBuilder.new
+        block.call(r) if block_given?
+        @model.rows << r.build
+        r
+      end
+
+      # Set table width
+      #
+      # @param value [Integer] Width in twips
+      # @param rule [String] Width rule ('auto', 'exact', 'pct')
+      # @return [self]
+      def width(value, rule: nil)
+        ensure_table_props
+        @model.properties.table_width ||= Properties::TableWidth.new
+        @model.properties.table_width.value = value
+        @model.properties.table_width.rule = rule if rule
+        self
+      end
+
+      # Set table indentation
+      #
+      # @param value [Integer] Indent in twips
+      # @return [self]
+      def indent(value)
+        ensure_table_props
+        @model.properties.table_indent ||= Properties::TableIndent.new
+        @model.properties.table_indent.value = value
+        self
+      end
+
+      # Set table borders
+      #
+      # @param sides [Hash] Border specifications by side
+      # @return [self]
+      def borders(**sides)
+        ensure_table_props
+        @model.properties.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
+          @model.properties.borders.send("#{side}=", border)
+        end
+        self
+      end
+
+      # Set table shading
+      #
+      # @param fill [String] Fill color
+      # @return [self]
+      def shading(fill:)
+        ensure_table_props
+        @model.properties.shading = Properties::Shading.new(fill: fill)
+        self
+      end
+
+      # Set table alignment
+      #
+      # @param value [String] :left, :center, :right
+      # @return [self]
+      def align=(value)
+        ensure_table_props
+        @model.properties.justification = Properties::TableJustification.new(value: value.to_s)
+        self
+      end
+
+      # Return the underlying Table model
+      def build
+        @model
+      end
+
+      private
+
+      def ensure_table_props
+        @model.properties ||= Wordprocessingml::TableProperties.new
+      end
+    end
+  end
+end

data/lib/uniword/builder/table_cell_builder.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and configures TableCell objects.
+    #
+    # @example Create a table cell
+    #   r.cell do |c|
+    #     c << 'Cell content'
+    #     c.shading(fill: '4472C4')
+    #   end
+    class TableCellBuilder
+      attr_reader :model
+
+      def initialize(model = nil)
+        @model = model || Wordprocessingml::TableCell.new
+      end
+
+      # Wrap an existing TableCell model
+      def self.from_model(model)
+        new(model)
+      end
+
+      # Append content to the cell. Routes by type:
+      # - String → creates a Paragraph with a Run
+      # - Paragraph → appends to paragraphs
+      # - Table → appends to nested tables
+      #
+      # @param element [String, Paragraph, Table]
+      # @return [self]
+      def <<(element)
+        case element
+        when String
+          para = Wordprocessingml::Paragraph.new
+          para.runs << Wordprocessingml::Run.new(text: element)
+          @model.paragraphs << para
+        when Wordprocessingml::Paragraph
+          @model.paragraphs << element
+        when Wordprocessingml::Table
+          @model.tables << element
+        when ParagraphBuilder
+          @model.paragraphs << element.build
+        else
+          raise ArgumentError, "Cannot add #{element.class} to table cell"
+        end
+        self
+      end
+
+      # Set cell shading
+      #
+      # @param fill [String] Fill color
+      # @param color [String, nil] Shading color
+      # @param pattern [String] Pattern (default 'clear')
+      # @return [self]
+      def shading(fill:, color: nil, pattern: 'clear')
+        ensure_cell_props
+        @model.properties.shading = Properties::Shading.new(
+          fill: fill, color: color, pattern: pattern
+        )
+        self
+      end
+
+      # Set cell width
+      #
+      # @param value [Integer] Width in twips
+      # @param rule [String] Width rule ('auto', 'exact', 'pct')
+      # @return [self]
+      def width(value, rule: nil)
+        ensure_cell_props
+        @model.properties.width ||= Properties::CellWidth.new
+        @model.properties.width.value = value
+        @model.properties.width.rule = rule if rule
+        self
+      end
+
+      # Set vertical alignment
+      #
+      # @param value [String] :top, :center, :bottom, :both
+      # @return [self]
+      def vertical_align(value)
+        ensure_cell_props
+        @model.properties.vertical_align = Properties::CellVerticalAlign.new(value: value.to_s)
+        self
+      end
+
+      # Set cell borders
+      #
+      # @param sides [Hash] Border specifications by side
+      # @return [self]
+      def borders(**sides)
+        ensure_cell_props
+        @model.properties.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
+          @model.properties.borders.send("#{side}=", border)
+        end
+        self
+      end
+
+      # Set column span
+      #
+      # @param count [Integer] Number of columns to span
+      # @return [self]
+      def column_span(count)
+        ensure_cell_props
+        @model.properties.grid_span =
+          Wordprocessingml::ValInt.new(value: count)
+        self
+      end
+
+      # Set row span
+      #
+      # @param count [Integer] Number of rows to span
+      # @return [self]
+      def row_span(count)
+        ensure_cell_props
+        @model.properties.v_merge =
+          Wordprocessingml::ValInt.new(value: count)
+        self
+      end
+
+      # Return the underlying TableCell model
+      def build
+        @model
+      end
+
+      private
+
+      def ensure_cell_props
+        @model.properties ||= Wordprocessingml::TableCellProperties.new
+      end
+    end
+  end
+end

data/lib/uniword/builder/table_row_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and configures TableRow objects.
+    #
+    # @example Create a table row
+    #   t.row do |r|
+    #     r.cell(text: 'Header 1')
+    #     r.cell(text: 'Header 2')
+    #   end
+    class TableRowBuilder
+      attr_reader :model
+
+      def initialize(model = nil)
+        @model = model || Wordprocessingml::TableRow.new
+      end
+
+      # Wrap an existing TableRow model
+      def self.from_model(model)
+        new(model)
+      end
+
+      # Create and add a cell to the row
+      #
+      # @param text [String, nil] Optional text content (creates a paragraph)
+      # @yield [TableCellBuilder] Builder for cell configuration
+      # @return [TableCellBuilder] The cell builder
+      def cell(text: nil, &block)
+        c = TableCellBuilder.new
+        c << text if text
+        block.call(c) if block_given?
+        @model.cells << c.build
+        c
+      end
+
+      # Set row height
+      #
+      # @param value [Integer] Height in twips
+      # @param rule [String] Height rule ('auto', 'exact', 'atLeast')
+      # @return [self]
+      def height(value, rule: nil)
+        @model.properties ||= Wordprocessingml::TableRowProperties.new
+        @model.properties.height = value
+        @model.properties.height_rule = rule if rule
+        self
+      end
+
+      # Set as table header row
+      #
+      # @param value [Boolean] Header row state (default true)
+      # @return [self]
+      def header_row(value = true)
+        @model.properties ||= Wordprocessingml::TableRowProperties.new
+        @model.properties.table_header = value
+        self
+      end
+
+      # Return the underlying TableRow model
+      def build
+        @model
+      end
+    end
+  end
+end

data/lib/uniword/builder/theme_builder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and applies themes to documents.
+    #
+    # Themes control the overall look of a document through color schemes,
+    # font schemes, and format schemes.
+    #
+    # @example Apply a bundled theme
+    #   doc.theme('atlas')
+    #
+    # @example Apply and customize a theme
+    #   doc.theme('office') do |t|
+    #     t.colors(accent1: 'FF0000', accent2: '00FF00')
+    #     t.fonts(major: 'Georgia', minor: 'Calibri')
+    #   end
+    class ThemeBuilder
+      def initialize(document)
+        @document = document
+      end
+
+      # Apply a named bundled theme
+      #
+      # Bundled themes are YAML files in data/themes/.
+      # Available themes: Themes::Theme.available_themes
+      #
+      # @param name [String] Theme name (e.g., 'atlas', 'badge', 'office')
+      # @return [self]
+      def apply(name)
+        friendly = Themes::Theme.load(name)
+        @document.model.theme =
+          Themes::ThemeTransformation.new.to_word(friendly)
+        self
+      end
+
+      # Apply a theme from a .thmx file
+      #
+      # @param path [String] Path to .thmx theme file
+      # @param variant [String, nil] Theme variant
+      # @return [self]
+      def apply_file(path, variant: nil)
+        @document.model.theme =
+          Drawingml::Theme.from_thmx(path, variant: variant)
+        self
+      end
+
+      # Override theme colors
+      #
+      # @param overrides [Hash] Color slot overrides (e.g., accent1: 'FF0000')
+      # @return [self]
+      def colors(**overrides)
+        theme = @document.model.theme
+        return self unless theme
+
+        scheme = theme.theme_elements&.clr_scheme
+        return self unless scheme
+
+        overrides.each do |slot, color|
+          scheme[slot.to_sym] = color
+        end
+        self
+      end
+
+      # Override theme fonts
+      #
+      # @param major [String, nil] Major font (headings)
+      # @param minor [String, nil] Minor font (body)
+      # @return [self]
+      def fonts(major: nil, minor: nil)
+        theme = @document.model.theme
+        return self unless theme
+
+        fs = theme.theme_elements&.font_scheme
+        return self unless fs
+
+        fs.major_font = major if major
+        fs.minor_font = minor if minor
+        self
+      end
+
+      # Get a theme color value
+      #
+      # @param slot [Symbol, String] Color slot (e.g., :accent1, :dk1)
+      # @return [String, nil] Hex color value
+      def color(slot)
+        @document.model.theme&.color(slot.to_sym)
+      end
+
+      # List available bundled themes
+      #
+      # @return [Array<String>] Theme names
+      def available
+        Themes::Theme.available_themes
+      end
+    end
+  end
+end