uniword 1.0.0

data/lib/uniword/builder/paragraph_builder.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and configures Paragraph objects.
+    #
+    # Uses << operator to append child elements with smart type routing.
+    #
+    # @example Create a simple paragraph
+    #   para = ParagraphBuilder.new
+    #   para << 'Hello World'
+    #   para.build
+    #
+    # @example Styled paragraph with mixed content
+    #   para = ParagraphBuilder.new
+    #   para.style = 'Heading1'
+    #   para << Builder.text('Title', bold: true, size: 24)
+    #   para << Builder.hyperlink('https://example.com', 'link')
+    #   para << Builder.tab_stop(position: 7200)
+    #   para.build
+    class ParagraphBuilder
+      attr_reader :model
+
+      def initialize(model = nil)
+        @model = model || Wordprocessingml::Paragraph.new
+      end
+
+      # Wrap an existing Paragraph model for manipulation
+      #
+      # @param model [Wordprocessingml::Paragraph] Existing paragraph
+      # @return [ParagraphBuilder]
+      def self.from_model(model)
+        new(model)
+      end
+
+      # Append a child element. Routes by type:
+      # - String → creates a Run
+      # - Run → appends to runs
+      # - Hyperlink → appends to hyperlinks
+      # - TabStop → appends to properties.tabs
+      # - BookmarkStart/End → appends to bookmarks
+      # - StructuredDocumentTag → appends to sdts
+      #
+      # @param element [String, Run, Hyperlink, Properties::TabStop, ...]
+      # @return [self]
+      def <<(element)
+        case element
+        when String
+          @model.runs << Wordprocessingml::Run.new(text: element)
+        when Wordprocessingml::Run
+          @model.runs << element
+        when Wordprocessingml::Hyperlink
+          @model.hyperlinks << element
+        when Properties::TabStop
+          ensure_properties
+          @model.properties.tabs ||= Properties::Tabs.new
+          @model.properties.tabs << element
+        when Wordprocessingml::BookmarkStart
+          @model.bookmark_starts << element
+        when Wordprocessingml::BookmarkEnd
+          @model.bookmark_ends << element
+        when Wordprocessingml::StructuredDocumentTag
+          @model.sdts << element
+        when RunBuilder
+          @model.runs << element.build
+        else
+          raise ArgumentError, "Cannot add #{element.class} to paragraph"
+        end
+        self
+      end
+
+      # Set paragraph style
+      #
+      # @param name [String] Style name or ID
+      # @return [self]
+      def style=(name)
+        ensure_properties.style = Properties::StyleReference.new(value: name)
+        self
+      end
+
+      # Set paragraph alignment
+      #
+      # @param value [String, Symbol] :left, :center, :right, :justify
+      # @return [self]
+      def align=(value)
+        ensure_properties.alignment = Properties::Alignment.new(value: 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
+      # @param rule [String, nil] Line rule ('auto', 'exact', 'atLeast')
+      # @return [self]
+      def spacing(before: nil, after: nil, line: nil, rule: nil)
+        ensure_properties.spacing ||= Properties::Spacing.new
+        props = @model.properties.spacing
+        props.before = before if before
+        props.after = after if after
+        props.line = line if line
+        props.line_rule = rule if rule
+        self
+      end
+
+      # Set paragraph indentation
+      #
+      # @param left [Integer, nil] Left indent in twips
+      # @param right [Integer, nil] Right indent in twips
+      # @param first_line [Integer, nil] First line indent in twips
+      # @param hanging [Integer, nil] Hanging indent in twips
+      # @return [self]
+      def indent(left: nil, right: nil, first_line: nil, hanging: nil)
+        ensure_properties.indentation ||= Properties::Indentation.new
+        ind = @model.properties.indentation
+        ind.left = left if left
+        ind.right = right if right
+        ind.first_line = first_line if first_line
+        ind.hanging = hanging if hanging
+        self
+      end
+
+      # Set paragraph borders
+      #
+      # @param sides [Hash] Border specifications by side
+      # @option sides [Hash, String] :top Border hash or color string
+      # @option sides [Hash, String] :bottom Border hash or color string
+      # @option sides [Hash, String] :left Border hash or color string
+      # @option sides [Hash, String] :right Border hash or color string
+      # @return [self]
+      def borders(**sides)
+        ensure_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 paragraph 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_properties.shading = Properties::Shading.new(
+          fill: fill, color: color, pattern: pattern
+        )
+        self
+      end
+
+      # Set numbering
+      #
+      # @param num_id [Integer] Numbering definition ID
+      # @param level [Integer] Numbering level (0-based, default 0)
+      # @return [self]
+      def numbering(num_id, level = 0)
+        props = ensure_properties
+        props.num_id = num_id
+        props.ilvl = level
+        props.numbering_properties = Properties::NumberingProperties.new(
+          num_id: Properties::NumberingId.new(value: num_id),
+          ilvl: Properties::NumberingLevel.new(value: level)
+        )
+        self
+      end
+
+      # Set keep next
+      #
+      # @param value [Boolean] Keep with next paragraph (default true)
+      # @return [self]
+      def keep_next(value = true)
+        ensure_properties.keep_next = value
+        self
+      end
+
+      # Set page break before
+      #
+      # @param value [Boolean] Page break before (default true)
+      # @return [self]
+      def page_break_before(value = true)
+        ensure_properties.page_break_before = value
+        self
+      end
+
+      # Set contextual spacing
+      #
+      # @param value [Boolean] Contextual spacing state
+      # @return [self]
+      def contextual_spacing=(value)
+        ensure_properties.contextual_spacing = value
+        self
+      end
+
+      # Set outline level
+      #
+      # @param value [String] Outline level
+      # @return [self]
+      def outline_level=(value)
+        ensure_properties.outline_level = value
+        self
+      end
+
+      # Return the underlying Paragraph model
+      #
+      # @return [Wordprocessingml::Paragraph]
+      def build
+        @model
+      end
+
+      private
+
+      # Ensure ParagraphProperties exist on the model
+      #
+      # @return [Wordprocessingml::ParagraphProperties]
+      def ensure_properties
+        @model.properties ||= Wordprocessingml::ParagraphProperties.new
+        @model.properties
+      end
+    end
+  end
+end

data/lib/uniword/builder/run_builder.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds and configures Run objects with formatting.
+    #
+    # @example Create a formatted run
+    #   run = RunBuilder.new.bold.italic.color('FF0000').size(12).build
+    #
+    # @example Wrap an existing run
+    #   builder = RunBuilder.from_model(existing_run)
+    #   builder.bold.build
+    class RunBuilder
+      attr_reader :model
+
+      def initialize(model = nil)
+        @model = model || Wordprocessingml::Run.new
+      end
+
+      # Wrap an existing Run model for manipulation
+      #
+      # @param model [Wordprocessingml::Run] Existing run
+      # @return [RunBuilder]
+      def self.from_model(model)
+        new(model)
+      end
+
+      # Set text content
+      #
+      # @param value [String] Text content
+      # @return [self]
+      def text(value)
+        @model.text = value
+        self
+      end
+
+      # Set bold formatting
+      #
+      # @param value [Boolean] Bold state (default true)
+      # @return [self]
+      def bold(value = true)
+        ensure_props.bold = Properties::Bold.new(value: value)
+        self
+      end
+
+      # Set italic formatting
+      #
+      # @param value [Boolean] Italic state (default true)
+      # @return [self]
+      def italic(value = true)
+        ensure_props.italic = Properties::Italic.new(value: value)
+        self
+      end
+
+      # Set underline formatting
+      #
+      # @param value [String, Boolean] Underline style or boolean
+      # @return [self]
+      def underline(value = 'single')
+        val = value == true ? 'single' : value.to_s
+        ensure_props.underline = Properties::Underline.new(value: val)
+        self
+      end
+
+      # Set font color
+      #
+      # @param value [String] Color as hex string
+      # @return [self]
+      def color(value)
+        ensure_props.color = Properties::ColorValue.new(value: value.to_s)
+        self
+      end
+
+      # Set font name
+      #
+      # @param value [String] Font family name
+      # @return [self]
+      def font(value)
+        ensure_props.font = value
+        self
+      end
+
+      # Set font size in points
+      #
+      # @param points [Integer] Font size in points
+      # @return [self]
+      def size(points)
+        ensure_props.size = Properties::FontSize.new(value: points.to_i * 2)
+        self
+      end
+
+      # Set highlight color
+      #
+      # @param value [String] Highlight color name
+      # @return [self]
+      def highlight(value)
+        ensure_props.highlight = Properties::Highlight.new(value: value.to_s)
+        self
+      end
+
+      # Set strikethrough
+      #
+      # @param value [Boolean] Strike state (default true)
+      # @return [self]
+      def strike(value = true)
+        ensure_props.strike = Properties::Strike.new(value: value)
+        self
+      end
+
+      # Set double strikethrough
+      #
+      # @param value [Boolean] Double strike state (default true)
+      # @return [self]
+      def double_strike(value = true)
+        ensure_props.double_strike = Properties::DoubleStrike.new(value: value)
+        self
+      end
+
+      # Set small caps
+      #
+      # @param value [Boolean] Small caps state (default true)
+      # @return [self]
+      def small_caps(value = true)
+        ensure_props.small_caps = Properties::SmallCaps.new(value: value)
+        self
+      end
+
+      # Set all caps
+      #
+      # @param value [Boolean] Caps state (default true)
+      # @return [self]
+      def caps(value = true)
+        ensure_props.caps = Properties::Caps.new(value: value)
+        self
+      end
+
+      # Set superscript
+      #
+      # @return [self]
+      def superscript
+        ensure_props.vertical_align = Properties::VerticalAlign.new(value: 'superscript')
+        self
+      end
+
+      # Set subscript
+      #
+      # @return [self]
+      def subscript
+        ensure_props.vertical_align = Properties::VerticalAlign.new(value: 'subscript')
+        self
+      end
+
+      # Set 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_props.shading = Properties::Shading.new(
+          fill: fill, color: color, pattern: pattern
+        )
+        self
+      end
+
+      # Set shadow
+      #
+      # @param value [Boolean] Shadow state (default true)
+      # @return [self]
+      def shadow(value = true)
+        ensure_props.shadow = Properties::Shadow.new(value: value)
+        self
+      end
+
+      # Set emboss
+      #
+      # @param value [Boolean] Emboss state (default true)
+      # @return [self]
+      def emboss(value = true)
+        ensure_props.emboss = Properties::Emboss.new(value: value)
+        self
+      end
+
+      # Set imprint
+      #
+      # @param value [Boolean] Imprint state (default true)
+      # @return [self]
+      def imprint(value = true)
+        ensure_props.imprint = Properties::Imprint.new(value: value)
+        self
+      end
+
+      # Set outline
+      #
+      # @param value [Boolean] Outline state (default true)
+      # @return [self]
+      def outline(value = true)
+        ensure_props.outline = Properties::Outline.new(value: value)
+        self
+      end
+
+      # Set kerning
+      #
+      # @param value [Integer] Kerning threshold in half-points
+      # @return [self]
+      def kerning(value)
+        ensure_props.kerning = Properties::Kerning.new(value: value)
+        self
+      end
+
+      # Set character spacing
+      #
+      # @param value [Integer] Spacing in twips
+      # @return [self]
+      def character_spacing(value)
+        ensure_props.character_spacing = Properties::CharacterSpacing.new(value: value)
+        self
+      end
+
+      # Set text expansion (width scale)
+      #
+      # @param value [Integer] Percentage (e.g., 200 for double width)
+      # @return [self]
+      def text_expansion(value)
+        ensure_props.width_scale = Properties::WidthScale.new(value: value)
+        self
+      end
+
+      # Set language
+      #
+      # @param code [String] Language code (e.g., 'en-US')
+      # @return [self]
+      def language(code)
+        ensure_props.language = Properties::Language.new(val: code)
+        self
+      end
+
+      # Set emphasis mark
+      #
+      # @param value [String] Emphasis mark type
+      # @return [self]
+      def emphasis_mark(value)
+        ensure_props.emphasis_mark = Properties::EmphasisMark.new(value: value)
+        self
+      end
+
+      # Set position (superscript/subscript offset)
+      #
+      # @param value [Integer] Position in half-points
+      # @return [self]
+      def position(value)
+        ensure_props.position = Properties::Position.new(value: value)
+        self
+      end
+
+      # Add a Drawing to the run
+      #
+      # @param drawing [Wordprocessingml::Drawing] Drawing element
+      # @return [self]
+      def drawing(drawing)
+        drawings = @model.instance_variable_get(:@drawings) || []
+        drawings << drawing
+        @model.instance_variable_set(:@drawings, drawings)
+        self
+      end
+
+      # Return the underlying Run model
+      #
+      # @return [Wordprocessingml::Run]
+      def build
+        @model
+      end
+
+      private
+
+      # Ensure RunProperties exist on the model
+      #
+      # @return [Wordprocessingml::RunProperties]
+      def ensure_props
+        @model.properties ||= Wordprocessingml::RunProperties.new
+        @model.properties
+      end
+    end
+  end
+end

data/lib/uniword/builder/sdt_builder.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Builder
+    # Builds Structured Document Tags (content controls).
+    #
+    # Supports text controls, date pickers, dropdown lists, bibliography
+    # placeholders, and document part references.
+    #
+    # @example Create a text content control
+    #   sdt = SdtBuilder.text(tag: 'title', alias: 'Document Title')
+    #   doc.paragraph { |p| p << sdt.build }
+    #
+    # @example Create a date picker
+    #   sdt = SdtBuilder.date(tag: 'date1', format: 'yyyy-MM-dd')
+    #   doc.paragraph { |p| p << sdt.build }
+    #
+    # @example Create a bibliography placeholder
+    #   sdt = SdtBuilder.bibliography
+    #   doc.paragraph { |p| p << sdt.build }
+    class SdtBuilder
+      attr_reader :model
+
+      def initialize
+        @model = Wordprocessingml::StructuredDocumentTag.new
+        @sdt_id_counter = 0
+      end
+
+      # Wrap an existing StructuredDocumentTag model
+      #
+      # @param model [Wordprocessingml::StructuredDocumentTag]
+      # @return [SdtBuilder]
+      def self.from_model(model)
+        builder = allocate
+        builder.instance_variable_set(:@model, model)
+        builder
+      end
+
+      # Set the SDT identifier
+      #
+      # @param value [Integer] Unique ID (auto-generated if nil)
+      # @return [self]
+      def id(value = nil)
+        properties.id = Wordprocessingml::StructuredDocumentTag::Id.new(
+          value: value || next_id
+        )
+        self
+      end
+
+      # Set the developer tag
+      #
+      # @param value [String] Tag name
+      # @return [self]
+      def tag(value)
+        properties.tag = Wordprocessingml::StructuredDocumentTag::Tag.new(
+          value: value
+        )
+        self
+      end
+
+      # Set the display alias
+      #
+      # @param value [String] Alias name
+      # @return [self]
+      def alias(value)
+        properties.alias_name = Wordprocessingml::StructuredDocumentTag::Alias.new(
+          value: value
+        )
+        self
+      end
+
+      # Set the lock / content cannot be edited
+      #
+      # @param value [Boolean] Lock content (default true)
+      # @return [self]
+      def lock(_value = true)
+        properties.temporary = Wordprocessingml::StructuredDocumentTag::Temporary.new
+        self
+      end
+
+      # Set placeholder text showing the placeholder header
+      #
+      # @param value [Boolean] Show placeholder (default true)
+      # @return [self]
+      def showing_placeholder(_value = true)
+        properties.showing_placeholder_header = Wordprocessingml::StructuredDocumentTag::ShowingPlaceholderHeader.new
+        self
+      end
+
+      # Return the underlying StructuredDocumentTag model
+      #
+      # @return [Wordprocessingml::StructuredDocumentTag]
+      def build
+        # Auto-assign ID if not set
+        unless properties.id
+          properties.id = Wordprocessingml::StructuredDocumentTag::Id.new(
+            value: next_id
+          )
+        end
+        @model
+      end
+
+      # Access the properties object, initializing if needed
+      #
+      # @return [Wordprocessingml::StructuredDocumentTagProperties]
+      def properties
+        @model.properties ||= Wordprocessingml::StructuredDocumentTagProperties.new
+        @model.properties
+      end
+
+      # --- Factory methods ---
+
+      # Create a plain text content control
+      #
+      # @param tag [String, nil] Developer tag
+      # @param alias_name [String, nil] Display name
+      # @param placeholder_text [String, nil] Placeholder text
+      # @param lock [Boolean] Lock content
+      # @return [SdtBuilder]
+      def self.text(tag: nil, alias_name: nil, placeholder_text: nil, lock: false)
+        sdt = new
+        sdt.tag(tag) if tag
+        sdt.alias(alias_name) if alias_name
+        sdt.lock if lock
+
+        # Text control flag
+        sdt.properties.text = Wordprocessingml::StructuredDocumentTag::Text.new
+
+        sdt.showing_placeholder if placeholder_text
+        sdt
+      end
+
+      # Create a date picker content control
+      #
+      # @param tag [String, nil] Developer tag
+      # @param format [String] Date format (default 'M/d/yyyy')
+      # @param locale [String] Locale (default 'en-US')
+      # @param calendar [String] Calendar type (default 'gregorian')
+      # @return [SdtBuilder]
+      def self.date(tag: nil, format: 'M/d/yyyy', locale: 'en-US',
+                    calendar: 'gregorian')
+        sdt = new
+        sdt.tag(tag) if tag
+
+        # Date control
+        date = Wordprocessingml::StructuredDocumentTag::Date.new
+        date.date_format = Wordprocessingml::StructuredDocumentTag::DateFormat.new(
+          value: format
+        )
+        date.lid = Wordprocessingml::StructuredDocumentTag::Lid.new(value: locale)
+        date.store_mapped_data_as = Wordprocessingml::StructuredDocumentTag::StoreMappedDataAs.new(
+          value: 'dateTime'
+        )
+        date.calendar = Wordprocessingml::StructuredDocumentTag::Calendar.new(
+          value: calendar
+        )
+        sdt.properties.date = date
+        sdt
+      end
+
+      # Create a bibliography placeholder
+      #
+      # @return [SdtBuilder]
+      def self.bibliography
+        sdt = new
+
+        # Bibliography flag
+        sdt.properties.bibliography = Wordprocessingml::StructuredDocumentTag::Bibliography.new
+
+        # DocPartObj with bibliography gallery
+        dpo = Wordprocessingml::StructuredDocumentTag::DocPartObj.new
+        dpo.doc_part_gallery = Wordprocessingml::StructuredDocumentTag::DocPartGallery.new(
+          value: 'Bibliographies'
+        )
+        dpo.doc_part_unique = Wordprocessingml::StructuredDocumentTag::DocPartUnique.new
+        sdt.properties.doc_part_obj = dpo
+        sdt
+      end
+
+      # Create a document part content control (e.g., Table of Contents)
+      #
+      # @param gallery [String] Gallery name (e.g., 'Table of Contents')
+      # @param unique [Boolean] Mark as unique
+      # @return [SdtBuilder]
+      def self.doc_part(gallery:, unique: true)
+        sdt = new
+
+        dpo = Wordprocessingml::StructuredDocumentTag::DocPartObj.new
+        dpo.doc_part_gallery = Wordprocessingml::StructuredDocumentTag::DocPartGallery.new(
+          value: gallery
+        )
+        dpo.doc_part_unique = Wordprocessingml::StructuredDocumentTag::DocPartUnique.new if unique
+        sdt.properties.doc_part_obj = dpo
+        sdt
+      end
+
+      private
+
+      def next_id
+        @sdt_id_counter += 1
+        @sdt_id_counter
+      end
+    end
+  end
+end