liquid_xlsx 0.1.0

data/lib/liquid_xlsx/image.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "digest"
+require "stringio"
+
+module LiquidXlsx
+  # Polymorphic image source with format detection and deduplication.
+  #
+  # Accepts:
+  # - Raw binary String (auto-detects format from magic bytes)
+  # - Image (idempotent)
+  # - IO / object with #read
+  # - Hash: { data:, io:, path:, url:, content_type:, width:, height: }
+  # - String that looks like a path/URL (requires images.loader)
+  class Image
+    attr_reader :binary, :content_type, :extension
+
+    # Magic byte signatures for format detection.
+    SIGNATURES = {
+      "PNG" => ["\x89PNG\r\n\x1a\n".b, "image/png", "png"],
+      "JPEG" => ["\xFF\xD8\xFF".b, "image/jpeg", "jpeg"],
+      "GIF87a" => ["GIF87a".b, "image/gif", "gif"],
+      "GIF89a" => ["GIF89a".b, "image/gif", "gif"]
+    }.freeze
+
+    def initialize(binary:, content_type: nil, extension: nil)
+      @binary = binary.b
+      @content_type = content_type || detect_content_type(@binary)
+      raise_unknown_format(@content_type) unless @content_type
+
+      @extension = extension || detect_extension(@content_type)
+    end
+
+    # Polymorphic coercion.
+    # @param value [String, Image, IO, Hash] input value
+    # @param loader [#call] optional proc for resolving path/URL strings
+    # @return [Image]
+    # Maximum depth of nested coercion (loader indirections etc.). Prevents
+    # infinite recursion when a loader returns a string that itself looks like
+    # a path/URL (or the same value it was given).
+    MAX_COERCE_DEPTH = 4
+
+    def self.coerce(value, loader: nil, depth: 0)
+      if depth > MAX_COERCE_DEPTH
+        raise RenderError,
+              "Image source could not be resolved to binary data " \
+              "(loader kept returning unresolvable values)"
+      end
+
+      case value
+      when Image
+        value
+      when String
+        if value.b.start_with?(*signature_bytes)
+          # Raw binary — wrap directly
+          new(binary: value)
+        else
+          # Path or URL string — requires loader
+          raise_loader_required(loader, value) unless loader
+
+          raw = loader.call(value)
+          if raw.is_a?(String) && !raw.b.start_with?(*signature_bytes)
+            raise RenderError,
+                  "images.loader returned a string that is not recognized " \
+                  "image data for source '#{value}'"
+          end
+          coerce(raw, loader: loader, depth: depth + 1)
+        end
+      when Hash
+        coerce_hash(value, loader: loader)
+      else
+        if value.respond_to?(:read)
+          coerce(value.read, loader: loader, depth: depth + 1)
+        else
+          raise RenderError, "Unsupported image source type: #{value.class}"
+        end
+      end
+    end
+
+    # SHA-256 hash for deduplication.
+    # @return [String]
+    def sha256
+      @sha256 ||= Digest::SHA256.hexdigest(@binary)
+    end
+
+    # Native pixel dimensions [width, height] parsed from the binary header.
+    # Used to preserve aspect ratio when only width OR height is given.
+    # Returns nil when the format/size cannot be determined.
+    def native_dimensions
+      case @content_type
+      when "image/png"
+        png_dimensions
+      when "image/gif"
+        gif_dimensions
+      when "image/jpeg"
+        jpeg_dimensions
+      end
+    rescue StandardError
+      nil
+    end
+
+    class << self
+      private
+
+      def signature_bytes
+        SIGNATURES.values.map(&:first)
+      end
+
+      def coerce_hash(hash, loader:)
+        if hash.key?(:data)
+          new(
+            binary: hash[:data],
+            content_type: hash[:content_type],
+            extension: hash[:extension]
+          )
+        elsif hash.key?(:io) || hash.key?(:path) || hash.key?(:url)
+          source = hash[:io] || hash[:path] || hash[:url]
+          raise RenderError, "Image source is a path/URL but no loader configured" unless loader
+
+          raw = loader.call(source)
+          new(
+            binary: raw,
+            content_type: hash[:content_type],
+            extension: hash[:extension]
+          )
+        else
+          raise RenderError, "Image hash requires :data, :io, :path, or :url"
+        end
+      end
+
+      def raise_loader_required(_loader, value)
+        raise RenderError, "Image source '#{value}' appears to be a path/URL " \
+                           "but no images.loader configured"
+      end
+    end
+
+    private
+
+    # PNG: IHDR chunk holds 4-byte big-endian width/height at offsets 16/20
+    # (8-byte signature + 4-byte length + 4-byte "IHDR" type).
+    def png_dimensions
+      return nil if @binary.bytesize < 24
+
+      [@binary[16, 4].unpack1("N"), @binary[20, 4].unpack1("N")]
+    end
+
+    # GIF: logical screen descriptor holds 2-byte little-endian width/height
+    # at offsets 6/8 (right after the 6-byte "GIF87a"/"GIF89a" header).
+    def gif_dimensions
+      return nil if @binary.bytesize < 10
+
+      [@binary[6, 2].unpack1("v"), @binary[8, 2].unpack1("v")]
+    end
+
+    # JPEG: scan marker segments for a SOFn marker and read its 2-byte
+    # big-endian height/width. SOFn = C0-C3, C5-C7, C9-CB, CD-CF
+    # (C4=DHT, C8=JPG, CC=DAC are excluded).
+    def jpeg_dimensions
+      bytes = @binary.bytes
+      return nil if bytes.size < 9
+      return nil unless bytes[0] == 0xFF && bytes[1] == 0xD8
+
+      i = 2
+      while i < bytes.size - 9
+        return nil unless bytes[i] == 0xFF
+
+        marker = bytes[i + 1]
+        if (0xC0..0xC3).cover?(marker) || (0xC5..0xC7).cover?(marker) ||
+           (0xC9..0xCB).cover?(marker) || (0xCD..0xCF).cover?(marker)
+          height = (bytes[i + 5] << 8) | bytes[i + 6]
+          width = (bytes[i + 7] << 8) | bytes[i + 8]
+          return [width, height]
+        end
+        # Standalone markers carry no length payload.
+        return nil if [0xD8, 0xD9].include?(marker) || (0xD0..0xD7).cover?(marker) || marker == 0x01
+        # SOS (0xDA) marks the start of entropy-coded data; SOF must appear
+        # before it. Stop scanning to avoid misreading stuffed 0xFF bytes.
+        return nil if marker == 0xDA
+
+        length = (bytes[i + 2] << 8) | bytes[i + 3]
+        return nil if length < 2
+
+        i += 2 + length
+      end
+      nil
+    end
+
+    def detect_content_type(binary)
+      SIGNATURES.each_value do |(sig_prefix, ct, _ext)|
+        return ct if binary.start_with?(sig_prefix)
+      end
+      nil
+    end
+
+    def detect_extension(content_type)
+      {
+        "image/png" => "png",
+        "image/jpeg" => "jpeg",
+        "image/gif" => "gif"
+      }[content_type]
+    end
+
+    def raise_unknown_format(_content_type)
+      raise UnsupportedTemplateError,
+            "Unrecognized image format. Supported: PNG, JPEG, GIF. " \
+            "Set content_type explicitly if format is known."
+    end
+  end
+end

data/lib/liquid_xlsx/merge_cells_transformer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Handles transformation of merged cells when rows are inserted or deleted.
+  class MergeCellsTransformer
+    # Clone a merge range for a repeated row.
+    # @param merge_range [String] e.g., "A3:B3"
+    # @param row_offset [Integer] shift from original row
+    # @return [String] new merge range
+    def clone_for_row(merge_range, row_offset)
+      return nil if row_offset == 0
+
+      start_ref, end_ref = merge_range.split(":")
+      start = CellReference.new(start_ref)
+      end_ref = CellReference.new(end_ref)
+
+      new_start = start.shift(row_offset, 0)
+      new_end = end_ref.shift(row_offset, 0)
+      "#{new_start}:#{new_end}"
+    end
+
+    # Shift merge ranges that are below a block boundary.
+    # @param merge_range [String] original merge range
+    # @param boundary_start [Integer] first row of the block
+    # @param boundary_end [Integer] last row of the block
+    # @param row_delta [Integer] net row shift (positive = insert, negative = delete)
+    # @return [String, nil] new merge range or nil if it should be removed
+    def shift_below(merge_range, boundary_start, boundary_end, row_delta)
+      start_ref, end_ref = merge_range.split(":")
+      start = CellReference.new(start_ref)
+      end_ref = CellReference.new(end_ref)
+
+      # Check if merge crosses the boundary
+      if crosses_boundary?(start.row, end_ref.row, boundary_start, boundary_end)
+        return nil # marked for error
+      end
+
+      # If merge is completely below the boundary, shift it
+      if start.row >= boundary_start
+        new_start = start.shift(row_delta, 0)
+        new_end = end_ref.shift(row_delta, 0)
+        "#{new_start}:#{new_end}"
+      else
+        merge_range # above boundary, keep as is
+      end
+    end
+
+    # Check if a merge range crosses a structural block boundary.
+    # @param merge_start_row [Integer]
+    # @param merge_end_row [Integer]
+    # @param block_start [Integer]
+    # @param block_end [Integer]
+    # @return [Boolean]
+    def crosses_boundary?(merge_start_row, merge_end_row, block_start, block_end)
+      # Merge is completely inside the block - not crossing
+      return false if merge_start_row >= block_start && merge_end_row <= block_end
+      # Merge is completely above the block - not crossing
+      return false if merge_end_row < block_start
+      # Merge is completely below the block - not crossing
+      return false if merge_start_row > block_end
+
+      # Merge overlaps with block boundaries — crosses
+      true
+    end
+
+    # Check if merge is inside a range
+    # @param merge_start_row [Integer]
+    # @param merge_end_row [Integer]
+    # @param range_start [Integer]
+    # @param range_end [Integer]
+    # @return [Boolean]
+    def inside_range?(merge_start_row, merge_end_row, range_start, range_end)
+      merge_start_row >= range_start && merge_end_row <= range_end
+    end
+  end
+end