liquid_xlsx 0.1.0

data/lib/liquid_xlsx/cell_reference.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Parses and manipulates Excel cell references (A1 notation).
+  class CellReference
+    PATTERN = /\A
+      (?<col_absolute>\$)?(?<col>[A-Z]+)
+      (?<row_absolute>\$)?(?<row>\d+)
+    \z/x
+
+    attr_reader :col, :row, :col_absolute, :row_absolute
+
+    # @param ref [String] e.g. "A1", "$A$1", "A$1", "$A1", "AA10"
+    def initialize(ref)
+      match = PATTERN.match(ref)
+      raise ArgumentError, "Invalid cell reference: #{ref}" unless match
+
+      @col = match[:col]
+      @row = match[:row].to_i
+      @col_absolute = !match[:col_absolute].nil?
+      @row_absolute = !match[:row_absolute].nil?
+    end
+
+    # Shift the reference by given row and column deltas.
+    # @param row_delta [Integer]
+    # @param col_delta [Integer]
+    # @return [String] new cell reference
+    def shift(row_delta, col_delta = 0)
+      new_row = @row_absolute ? @row : @row + row_delta
+      new_col = @col_absolute ? @col : column_add(@col, col_delta)
+
+      col_prefix = @col_absolute ? "$" : ""
+      row_prefix = @row_absolute ? "$" : ""
+
+      "#{col_prefix}#{new_col}#{row_prefix}#{new_row}"
+    end
+
+    def to_s
+      col_prefix = @col_absolute ? "$" : ""
+      row_prefix = @row_absolute ? "$" : ""
+      "#{col_prefix}#{@col}#{row_prefix}#{@row}"
+    end
+
+    # Convert column letters to zero-based index.
+    # @param col [String] e.g. "A", "AA"
+    # @return [Integer]
+    def self.col_to_index(col)
+      result = 0
+      col.each_char do |c|
+        result = (result * 26) + (c.ord - "A".ord + 1)
+      end
+      result - 1
+    end
+
+    # Convert zero-based index to column letters.
+    # @param index [Integer]
+    # @return [String]
+    def self.index_to_col(index)
+      result = ""
+      n = index + 1
+      while n > 0
+        n -= 1
+        result = ((n % 26) + "A".ord).chr + result
+        n /= 26
+      end
+      result
+    end
+
+    private
+
+    # Add a delta to a column letter string.
+    # @param col [String] e.g. "A"
+    # @param delta [Integer]
+    # @return [String]
+    def column_add(col, delta)
+      index = self.class.col_to_index(col) + delta
+      raise ArgumentError, "Column index out of bounds: #{index}" if index < 0
+
+      self.class.index_to_col(index)
+    end
+  end
+end

data/lib/liquid_xlsx/drawing_builder.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module LiquidXlsx
+  # Builds OpenXML drawing parts (drawingN.xml and relationships) from collected
+  # image operations for a single worksheet.
+  class DrawingBuilder
+    XDR_NS = "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing"
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main"
+    R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+
+    def self.px_to_emu(px, dpi = 96)
+      ((px.to_f / dpi) * 914_400).round
+    end
+
+    def self.col_to_index(col)
+      col.to_s.upcase.each_char.reduce(0) do |acc, ch|
+        (acc * 26) + (ch.ord - "A".ord + 1)
+      end - 1
+    end
+
+    def self.row_to_zero(row)
+      row.to_i - 1
+    end
+
+    # @param sheet_ops [Array<Hash>] image operations for one sheet
+    # @param images_options [Hash] { loader:, default_dpi: }
+    # @param merge_refs [Array<String>] e.g. ["A1:C2", "D5:D6"] from rendered sheet
+    def initialize(sheet_ops, images_options = {}, merge_refs = [])
+      @ops = sheet_ops
+      @dpi = images_options.fetch(:default_dpi, 96)
+      @loader = images_options[:loader]
+      @merge_refs = merge_refs
+      @next_r_id = 1
+      @seen_sha = {}
+    end
+
+    def build
+      images = @ops.map { |op| coerce_image(op) }
+      return empty_result if images.all?(&:nil?)
+
+      anchors = []
+      media_items = []
+      anchor_idx = 0
+
+      images.each_with_index do |img, op_idx|
+        next if img.nil?
+
+        anchor_idx += 1
+
+        sha = img.sha256
+        unless @seen_sha.key?(sha)
+          @seen_sha[sha] = @next_r_id
+          media_items << { sha: sha, binary: img.binary, ext: img.extension }
+          @next_r_id += 1
+        end
+
+        op = @ops[op_idx]
+        anchor = build_anchor(img, anchor_idx, @seen_sha[sha], op)
+        anchors << anchor
+      end
+
+      drawing_xml = build_drawing_xml(anchors)
+      drawing_rels_xml = build_rels_xml(media_items)
+
+      { drawing_xml: drawing_xml, drawing_rels_xml: drawing_rels_xml, media_items: media_items }
+    end
+
+    private
+
+    def coerce_image(op)
+      source = op[:source]
+      Image.coerce(source, loader: @loader)
+    rescue LiquidXlsx::Error => e
+      # Re-raise with sheet/cell context if missing
+      if !e.respond_to?(:cell) || e.cell.nil?
+        raise RenderError.new(
+          e.message,
+          sheet: op[:source_sheet],
+          cell: op[:source_cell]
+        )
+      end
+      raise
+    rescue StandardError => e
+      raise RenderError.new(
+        "Failed to load image: #{e.message}",
+        sheet: op[:source_sheet],
+        cell: op[:source_cell]
+      )
+    end
+
+    def build_anchor(img, idx, r_id, op)
+      from_col = self.class.col_to_index(op[:anchor_col]) if op[:anchor_col]
+      from_row = self.class.row_to_zero(op[:anchor_row]) if op[:anchor_row]
+      from_col ||= 0
+      from_row ||= 0
+
+      to_col, to_row, ext_cx, ext_cy = determine_range(from_col, from_row, op, img)
+
+      if ext_cx || ext_cy
+        build_one_cell_anchor(idx, r_id, from_col, from_row, ext_cx, ext_cy)
+      else
+        build_two_cell_anchor(idx, r_id, from_col, from_row, to_col, to_row)
+      end
+    end
+
+    def build_two_cell_anchor(idx, r_id, from_col, from_row, to_col, to_row)
+      <<~ANCHOR
+        <xdr:twoCellAnchor editAs="oneCell">
+          <xdr:from><xdr:col>#{from_col}</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>#{from_row}</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from>
+          <xdr:to><xdr:col>#{to_col}</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>#{to_row}</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:to>
+          #{pic_xml(idx, r_id)}
+          <xdr:clientData/>
+        </xdr:twoCellAnchor>
+      ANCHOR
+    end
+
+    def build_one_cell_anchor(idx, r_id, from_col, from_row, ext_cx, ext_cy)
+      <<~ANCHOR
+        <xdr:oneCellAnchor>
+          <xdr:from><xdr:col>#{from_col}</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>#{from_row}</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from>
+          <xdr:ext cx="#{ext_cx}" cy="#{ext_cy}"/>
+          #{pic_xml(idx, r_id)}
+          <xdr:clientData/>
+        </xdr:oneCellAnchor>
+      ANCHOR
+    end
+
+    def pic_xml(idx, r_id)
+      <<~PIC
+        <xdr:pic>
+          <xdr:nvPicPr>
+            <xdr:cNvPr id="#{idx}" name="Image #{idx}" descr=""/>
+            <xdr:cNvPicPr><a:picLocks noChangeAspect="1"/></xdr:cNvPicPr>
+          </xdr:nvPicPr>
+          <xdr:blipFill>
+            <a:blip xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" r:embed="rId#{r_id}"/>
+            <a:stretch><a:fillRect/></a:stretch>
+          </xdr:blipFill>
+          <xdr:spPr>
+            <a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
+          </xdr:spPr>
+        </xdr:pic>
+      PIC
+    end
+
+    # Returns [to_col, to_row, ext_cx, ext_cy].
+    # ext_cx/ext_cy are EMU when width/height given, nil otherwise.
+    def determine_range(from_col, from_row, op, img = nil)
+      # Priority 1: explicit "to:" cell reference
+      if op[:to]
+        to_parts = op[:to].match(/\A([A-Z]+)(\d+)\z/i)
+        if to_parts
+          to_col = self.class.col_to_index(to_parts[1]) + 1
+          to_row = self.class.row_to_zero(to_parts[2]) + 1
+          # Shift to by the same row delta as anchor (for loops)
+          if op[:template_anchor_row]
+            delta = (op[:anchor_row] || 1) - op[:template_anchor_row]
+            to_row += delta
+          end
+          return [to_col, to_row, nil, nil]
+        end
+      end
+
+      # Priority 2: colspan/rowspan (relative)
+      if op[:colspan] || op[:rowspan]
+        to_col = from_col + (op[:colspan] || 1)
+        to_row = from_row + (op[:rowspan] || 1)
+        return [to_col, to_row, nil, nil]
+      end
+
+      # Priority 3: anchor is top-left of a merged range → fill the merge
+      merge_result = fill_merge_range(from_col, from_row)
+      return merge_result if merge_result
+
+      # Priority 4: width/height → single cell with fixed EMU extents.
+      # Both cx and cy are always produced (CT_Extent requires both); a
+      # missing dimension is derived from the image's native aspect ratio,
+      # falling back to a square when the header cannot be parsed.
+      if op[:width] || op[:height]
+        ext_cx, ext_cy = compute_extents(op, img)
+        return [from_col + 1, from_row + 1, ext_cx, ext_cy]
+      end
+
+      # Priority 5: default — single cell
+      [from_col + 1, from_row + 1, nil, nil]
+    end
+
+    # Compute EMU extents from width/height options. When only one dimension
+    # is supplied, the other is derived from the native pixel size so that
+    # the aspect ratio is preserved (or defaults to a square as a last resort).
+    def compute_extents(op, img)
+      width_px = op[:width]
+      height_px = op[:height]
+      native = img&.native_dimensions
+
+      if width_px && !height_px
+        nw, nh = native || [nil, nil]
+        height_px = (nw&.positive? ? (width_px.fdiv(nw) * nh).round : width_px)
+      elsif height_px && !width_px
+        nw, nh = native || [nil, nil]
+        width_px = (nh&.positive? ? (height_px.fdiv(nh) * nw).round : height_px)
+      end
+
+      [self.class.px_to_emu(width_px, @dpi), self.class.px_to_emu(height_px, @dpi)]
+    end
+
+    # If anchor (from_col, from_row) matches the top-left cell of any merged range,
+    # return [to_col, to_row, nil, nil] for the range's bottom-right + 1.
+    # Otherwise nil.
+    def fill_merge_range(from_col, from_row)
+      @merge_refs.each do |ref|
+        parts = ref.split(":")
+        next unless parts.length == 2
+
+        tl = CellReference.new(parts[0])
+        br = CellReference.new(parts[1])
+
+        tl_col = self.class.col_to_index(tl.col)
+        tl_row = self.class.row_to_zero(tl.row)
+        br_col = self.class.col_to_index(br.col) + 1
+        br_row = self.class.row_to_zero(br.row) + 1
+
+        if tl_col == from_col && tl_row == from_row
+          return [br_col, br_row, nil, nil]
+        end
+      end
+      nil
+    end
+
+    def build_drawing_xml(anchors)
+      <<~XML
+        <xdr:wsDr xmlns:xdr="#{XDR_NS}" xmlns:a="#{A_NS}">
+        #{anchors.join("\n")}
+        </xdr:wsDr>
+      XML
+    end
+
+    def build_rels_xml(media_items)
+      rels = media_items.each_with_index.map do |mi, idx|
+        format('<Relationship Id="rId%s" ' \
+               'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" ' \
+               'Target="../media/%s"/>', idx + 1, sha_filename(mi[:sha], mi[:ext]))
+      end.join("\n")
+
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+        #{rels}
+        </Relationships>
+      XML
+    end
+
+    def sha_filename(sha, ext)
+      "image_#{sha[0..11]}.#{ext}"
+    end
+
+    def empty_result
+      { drawing_xml: nil, drawing_rels_xml: nil, media_items: [] }
+    end
+  end
+end

data/lib/liquid_xlsx/errors.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  class Error < StandardError; end
+
+  class TemplateSyntaxError < Error
+    attr_reader :sheet, :row, :cell, :tag
+
+    def initialize(message, sheet: nil, row: nil, cell: nil, tag: nil)
+      @sheet = sheet
+      @row = row
+      @cell = cell
+      @tag = tag
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      parts = [message]
+      parts << "Sheet: #{sheet}" if sheet
+      parts << "Row: #{row}" if row
+      parts << "Cell: #{cell}" if cell
+      parts << "Tag: #{tag}" if tag
+      parts.join("\n")
+    end
+  end
+
+  class RenderError < Error
+    attr_reader :sheet, :row, :cell, :template
+
+    def initialize(message, sheet: nil, row: nil, cell: nil, template: nil)
+      @sheet = sheet
+      @row = row
+      @cell = cell
+      @template = template
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      parts = [message]
+      parts << "Sheet: #{sheet}" if sheet
+      parts << "Row: #{row}" if row
+      parts << "Cell: #{cell}" if cell
+      parts << "Template: #{template}" if template
+      parts.join("\n")
+    end
+  end
+
+  class MissingVariableError < RenderError; end
+
+  class UnsupportedTemplateError < Error
+    attr_reader :sheet, :row, :cell, :block_rows
+
+    def initialize(message, sheet: nil, row: nil, cell: nil, block_rows: nil)
+      @sheet = sheet
+      @row = row
+      @cell = cell
+      @block_rows = block_rows
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      parts = [message]
+      parts << "Sheet: #{sheet}" if sheet
+      parts << "Row: #{row}" if row
+      parts << "Cell: #{cell}" if cell
+      parts << "Block: rows #{block_rows}" if block_rows
+      parts.join("\n")
+    end
+  end
+
+  class InvalidXlsxError < Error; end
+
+  class OutputWriteError < Error; end
+end

data/lib/liquid_xlsx/filters.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Custom Liquid filters for xlsx template rendering.
+  module Filters
+    # No custom filters needed for MVP.
+    # Standard Liquid filters (date, etc.) are available.
+  end
+end

data/lib/liquid_xlsx/formula_translator.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "English"
+module LiquidXlsx
+  # Translates Excel formulas when rows are copied or shifted, and widens
+  # ranges that reference loop bodies after loops have expanded.
+  #
+  # Loop expansions are registered in RENDER coordinates: for each template row
+  # of a loop body we know the list of rendered row numbers it produced. A range
+  # like SUM(E3:E3) whose rows point into a loop body is rewritten to span from
+  # the first to the last rendered body row; all other relative references are
+  # shifted by the formula's own row delta.
+  class FormulaTranslator
+    # Pattern for cell references including sheet-qualified ones.
+    # Guards: a reference must not be preceded or followed by an identifier
+    # character, so tails of function names (LOG10, ATAN2) and defined names
+    # are not mistaken for cell references.
+    CELL_REF = /
+      (?<![A-Za-z0-9_$])
+      (?<sheet>(?:'[^']*'|[A-Za-z0-9_.]+)!)?  # optional sheet name
+      (?<col_abs>\$)?(?<col>[A-Z]{1,3})
+      (?<row_abs>\$)?(?<row>\d+)
+      (?![A-Za-z0-9_(])
+    /x
+
+    def initialize
+      # Each: { rows: {template_row => [rendered_row, ...]}, block_first:, block_last:, path: }
+      @expansions = []
+    end
+
+    # Register a loop expansion.
+    # @param rows [Hash{Integer => Array<Integer>}] template body row => rendered rows
+    # @param block_first [Integer] template row of {% for %}
+    # @param block_last [Integer] template row of {% endfor %}
+    # @param path [Array<Integer>] iteration indices of enclosing loops
+    def register_expansion(rows:, block_first:, block_last:, path: [])
+      @expansions << { rows: rows, block_first: block_first,
+                       block_last: block_last, path: path.dup.freeze }
+    end
+
+    # Whether a template row lies inside a registered loop block (i.e. the row
+    # was copied per iteration rather than moved).
+    def copied_row?(template_row)
+      return false unless template_row
+
+      @expansions.any? { |e| template_row.between?(e[:block_first], e[:block_last]) }
+    end
+
+    # Translate a formula.
+    # @param formula [String] the original formula (without leading =)
+    # @param row_delta [Integer] how many rows to shift (positive = down)
+    # @param col_delta [Integer] how many columns to shift
+    # @param template_row [Integer, nil] template row the formula lives on
+    #   (used to skip loop expansions for formulas inside the loop itself)
+    # @param copied [Boolean] copy semantics (references to other sheets shift
+    #   too, as in Excel copy/paste); move semantics leaves them untouched
+    # @param formula_path [Array<Integer>] iteration path of the formula cell
+    # @return [String] translated formula
+    def translate(formula, row_delta, col_delta = 0, template_row: nil, copied: true, formula_path: [])
+      refs = scan_refs(formula)
+      return formula if refs.empty?
+
+      mark_expanded_ranges(formula, refs, template_row, formula_path)
+
+      out = +""
+      last_pos = 0
+      refs.each do |ref|
+        out << formula[last_pos...ref[:pos]]
+        out << rebuild_ref(ref, row_delta, col_delta, copied)
+        last_pos = ref[:end_pos]
+      end
+      out << formula[last_pos..]
+      out
+    end
+
+    private
+
+    # Scan cell references with positions, ignoring text inside double-quoted
+    # string literals.
+    def scan_refs(formula)
+      masked = mask_strings(formula)
+      refs = []
+      masked.scan(CELL_REF) do
+        m = $LAST_MATCH_INFO
+        refs << {
+          pos: m.begin(0),
+          end_pos: m.end(0),
+          text: formula[m.begin(0)...m.end(0)],
+          sheet: m[:sheet] || "",
+          col_abs: m[:col_abs],
+          col: m[:col],
+          row_abs: m[:row_abs],
+          row: m[:row].to_i
+        }
+      end
+      refs
+    end
+
+    # Replace the contents of double-quoted string literals with spaces so that
+    # cell-ref-looking text inside them is neither shifted nor expanded.
+    # Positions are preserved (replacement has the same length).
+    def mask_strings(formula)
+      formula.gsub(/"(?:[^"]|"")*"/) { |s| "\"#{' ' * (s.length - 2)}\"" }
+    end
+
+    # Find range pairs (r1:r2) pointing into an expanded loop body and pin
+    # their rows to absolute rendered coordinates (stored as :fixed_row).
+    def mark_expanded_ranges(formula, refs, template_row, formula_path)
+      refs.each_cons(2) do |r1, r2|
+        next unless formula[r1[:end_pos]...r2[:pos]] == ":"
+        next if r1[:row_abs] || r2[:row_abs]
+        next unless r1[:sheet].empty? && r2[:sheet].empty?
+
+        exp = find_expansion(r1[:row], r2[:row], template_row, formula_path)
+        next unless exp
+
+        all_rendered = exp[:rows].values.flatten
+        next if all_rendered.empty? # empty collection: fall back to plain shift
+
+        r1[:fixed_row] = all_rendered.min
+        r2[:fixed_row] = all_rendered.max
+      end
+    end
+
+    # An expansion applies when both range rows lie within the loop block
+    # (body rows or the tag rows), at least one of them is a body row, the
+    # formula itself is outside the block, and the expansion's path is a
+    # prefix of the formula's path (so inner-loop expansions are only
+    # visible to formulas in the same iteration scope).
+    def find_expansion(row1, row2, template_row, formula_path)
+      @expansions.reverse_each.find do |exp|
+        next false unless path_prefix_of?(exp[:path], formula_path)
+        next false if template_row && template_row >= exp[:block_first] && template_row <= exp[:block_last]
+        next false unless row1.between?(exp[:block_first], exp[:block_last])
+        next false unless row2.between?(exp[:block_first], exp[:block_last])
+
+        exp[:rows].key?(row1) || exp[:rows].key?(row2)
+      end
+    end
+
+    def path_prefix_of?(exp_path, formula_path)
+      return true if exp_path.empty?
+      return false if exp_path.length > formula_path.length
+
+      exp_path.each_with_index.all? { |idx, i| idx == formula_path[i] }
+    end
+
+    def rebuild_ref(ref, row_delta, col_delta, copied)
+      # Move semantics: references to other sheets do not change when rows
+      # shift on this sheet.
+      return ref[:text] if !copied && !ref[:sheet].empty? && !ref[:fixed_row]
+
+      new_col = if ref[:col_abs]
+                  ref[:col]
+                else
+                  CellReference.index_to_col(CellReference.col_to_index(ref[:col]) + col_delta)
+                end
+      new_row = if ref[:fixed_row]
+                  ref[:fixed_row]
+                elsif ref[:row_abs]
+                  ref[:row]
+                else
+                  ref[:row] + row_delta
+                end
+      new_row = 1 if new_row < 1
+
+      "#{ref[:sheet]}#{ref[:col_abs] || ''}#{new_col}#{ref[:row_abs] || ''}#{new_row}"
+    end
+  end
+end