liquid_xlsx 0.1.0

data/lib/liquid_xlsx/workbook.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Represents the workbook and orchestrates rendering across all sheets.
+  class Workbook
+    attr_reader :package, :shared_strings, :options
+
+    def initialize(package, options = {})
+      @package = package
+      @options = options
+      @shared_strings = SharedStrings.new(package.shared_strings_xml)
+    end
+
+    # Render all worksheets with the given data.
+    # @param data [Hash, Liquid::Drop, #to_liquid] data to render (Hash/Drop,
+    #   or any object whose `#to_liquid` returns one)
+    # @return [Package] modified package
+    def render(data)
+      all_image_ops = []
+
+      if @options[:dynamic_sheets]
+        render_with_dynamic_sheets(data, all_image_ops)
+      else
+        render_existing_sheets(data, all_image_ops)
+      end
+
+      # Phase: build drawings from collected image ops
+      build_drawings(all_image_ops)
+
+      # Handle recalculation
+      if @options[:recalculate_formulas]
+        package.remove_calc_chain if package.calc_chain_xml
+        package.set_recalculation_flags
+      end
+
+      package
+    end
+
+    # Maximum sheet name length in Excel.
+    MAX_SHEET_NAME_LENGTH = 31
+
+    # Characters forbidden in Excel sheet names.
+    FORBIDDEN_SHEET_NAME_CHARS = %r{[:/\\\?\*\[\]]}
+
+    # Maximum deduplication attempts before giving up.
+    SHEET_NAME_DEDUP_MAX = 9999
+
+    private
+
+    def render_existing_sheets(data, all_image_ops = [])
+      package.sheets.each do |sheet_info|
+        xml = package.worksheet_xml(sheet_info[:r_id])
+        next unless xml
+
+        image_ops = []
+
+        worksheet = Worksheet.new(xml, sheet_info[:name], @shared_strings)
+        renderer = Renderer.new(worksheet, @options)
+        renderer.sheet_r_id = sheet_info[:r_id]
+        sheet_xml = renderer.render(data, image_ops: image_ops)
+        package.save_worksheet_xml(sheet_info[:r_id], sheet_xml)
+
+        all_image_ops.concat(image_ops) if image_ops.any?
+      end
+    end
+
+    def render_with_dynamic_sheets(data, all_image_ops = [])
+      # Phase 0: Save original sheet XMLs before rendering mutates them
+      original_xmls = {}
+      package.sheets.each do |sheet_info|
+        xml = package.worksheet_xml(sheet_info[:r_id])
+        original_xmls[sheet_info[:name]] = xml if xml
+      end
+
+      # Phase 0.5: Identify control and template sheets
+      control_names, template_names_from_tags = scan_sheet_tags
+
+      # Phase 1: Render all sheets EXCEPT template sheets, collecting
+      # {% sheet %} operations from control sheets along the way. Template
+      # sheets are skipped — they use local variables unavailable in global
+      # context and will be rendered in Phase 3 per-op. Ordinary sheets
+      # (neither control nor template) must still be rendered normally.
+      workbook_ops = []
+
+      package.sheets.each do |sheet_info|
+        next if template_names_from_tags.include?(sheet_info[:name])
+
+        xml = original_xmls[sheet_info[:name]]
+        next unless xml
+
+        image_ops = []
+        worksheet = Worksheet.new(xml, sheet_info[:name], @shared_strings)
+        renderer = Renderer.new(worksheet, @options)
+        renderer.sheet_r_id = sheet_info[:r_id]
+        sheet_xml = renderer.render(data, workbook_ops: workbook_ops, image_ops: image_ops)
+        package.save_worksheet_xml(sheet_info[:r_id], sheet_xml)
+        all_image_ops.concat(image_ops) if image_ops.any?
+      end
+
+      # Phase 2: Process collected operations
+      ops = workbook_ops
+      template_sheet_names = ops.map { |op| op[:template_sheet] }.uniq
+      # Merge template names from tag scanning with ops
+      template_sheet_names |= template_names_from_tags
+
+      # Ops source_sheet also identifies control sheets (for hide_control_sheets)
+      control_sheet_names = ops.map { |op| op[:source_sheet] }.compact.uniq
+      control_sheet_names |= control_names
+
+      # Phase 3: Create and render new sheets (using original template XML)
+      ops.each do |op|
+        create_and_render_sheet(op, data, original_xmls, all_image_ops)
+      end
+
+      # Phase 4: Cleanup — hide control sheets and template sheets
+      cleanup_sheets(control_sheet_names, template_sheet_names)
+    end
+
+    # Scan all sheets to find control sheets (containing {% sheet %} tags)
+    # and template sheet names referenced in those tags.
+    # Checks both inlineStr and shared string references.
+    # @return [Array<Array<String>>] [control_names, template_names]
+    def scan_sheet_tags
+      control_names = []
+      template_names = []
+
+      package.sheets.each do |sheet_info|
+        xml = package.worksheet_xml(sheet_info[:r_id])
+        next unless xml
+
+        texts = sheet_texts(xml)
+        combined = texts.join("\n")
+        next unless combined.include?("{% sheet")
+
+        control_names << sheet_info[:name]
+        combined.scan(/template:\s*"([^"]+)"/).each do |match|
+          template_names << match[0]
+        end
+      end
+
+      [control_names, template_names]
+    end
+
+    # Extract all cell text content from a worksheet XML.
+    # Covers both inlineStr and shared string references.
+    def sheet_texts(sheet_xml)
+      texts = []
+      doc = Nokogiri::XML(sheet_xml)
+      ns = doc.root&.namespace
+      return texts unless ns
+
+      doc.xpath("//xmlns:c", "xmlns" => ns.href).each do |c|
+        if c["t"] == "inlineStr"
+          t_el = c.at_xpath("xmlns:is/xmlns:t", "xmlns" => ns.href)
+          texts << (t_el&.text || "")
+        elsif c["t"] == "s"
+          v_el = c.at_xpath("xmlns:v", "xmlns" => ns.href)
+          next unless v_el
+
+          idx = v_el.text.to_i
+          texts << (@shared_strings[idx] || "")
+        end
+      end
+
+      texts
+    end
+
+    def create_and_render_sheet(op, global_data, original_xmls, all_image_ops)
+      source_sheet = package.find_sheet_by_name(op[:template_sheet])
+      unless source_sheet
+        raise UnsupportedTemplateError.new(
+          "Template sheet '#{op[:template_sheet]}' not found.",
+          sheet: op[:source_sheet],
+          row: op[:source_row],
+          cell: op[:source_cell]
+        )
+      end
+
+      source_xml = original_xmls[op[:template_sheet]]
+      raw_sheet_name = op[:name].to_s
+
+      safe_name = normalize_sheet_name(raw_sheet_name)
+      safe_name = deduplicate_sheet_name(safe_name)
+
+      new_sheet = package.clone_worksheet(
+        source_sheet_name: op[:template_sheet],
+        new_sheet_name: safe_name
+      )
+
+      image_ops = []
+
+      worksheet = Worksheet.new(source_xml, safe_name, @shared_strings)
+      renderer = Renderer.new(worksheet, @options)
+      renderer.sheet_r_id = new_sheet[:r_id]
+      # Inject the per-op local variable via `extra_scope` rather than
+      # `global_data.merge`, so `global_data` is free to be a Drop or any
+      # `#to_liquid` object. `extra_scope` keys are assigned directly onto
+      # the Liquid context as scope variables, which take priority during
+      # lookup (scopes are searched before environments).
+      rendered_xml = renderer.render(
+        global_data,
+        image_ops: image_ops,
+        extra_scope: { op[:as] => op[:data] }
+      )
+      package[new_sheet[:path]] = rendered_xml
+
+      # Associate image ops with the new sheet's r_id
+      image_ops.each { |io| io[:sheet_r_id] = new_sheet[:r_id] }
+      all_image_ops.concat(image_ops) if image_ops.any?
+    end
+
+    def cleanup_sheets(control_sheet_names, template_sheet_names)
+      if @options[:hide_control_sheets]
+        control_sheet_names.each { |name| package.hide_sheet(name) }
+      end
+
+      if @options[:hide_template_sheets]
+        template_sheet_names.each { |name| package.hide_sheet(name) }
+      end
+    end
+
+    # Build all drawing parts from collected image operations.
+    # Groups ops by sheet_r_id, builds drawing XML/rels for each sheet,
+    # adds media files and attaches drawings to worksheets.
+    def build_drawings(all_image_ops)
+      return if all_image_ops.empty?
+
+      images_options = @options[:images] || {}
+
+      # Group operations by sheet_r_id
+      by_sheet = all_image_ops.group_by { |op| op[:sheet_r_id] }
+
+      by_sheet.each do |sheet_r_id, sheet_ops|
+        # Parse merge ranges from the rendered worksheet XML
+        merge_refs = sheet_merge_refs(sheet_r_id)
+
+        builder = DrawingBuilder.new(sheet_ops, images_options, merge_refs)
+        result = builder.build
+        next if result[:drawing_xml].nil?
+
+        # Add all media files (dedup by SHA inside package.add_media)
+        result[:media_items].each do |mi|
+          package.add_media(mi[:binary], mi[:ext])
+        end
+
+        # Attach drawing to worksheet
+        package.attach_drawing(
+          sheet_r_id: sheet_r_id,
+          drawing_xml: result[:drawing_xml],
+          drawing_rels_xml: result[:drawing_rels_xml]
+        )
+      end
+    end
+
+    # Normalize a sheet name to be valid for Excel.
+    # - Removes forbidden characters
+    # - Truncates to 31 characters
+    # - Ensures non-empty (falls back to "Sheet" if empty after normalization)
+    def normalize_sheet_name(name)
+      name = name.to_s.dup.force_encoding("UTF-8")
+      name = name.scrub("_") unless name.valid_encoding?
+      name.gsub!(FORBIDDEN_SHEET_NAME_CHARS, "")
+      name = name[0, MAX_SHEET_NAME_LENGTH] if name.length > MAX_SHEET_NAME_LENGTH
+      name.strip!
+
+      name = "Sheet" if name.empty?
+      name
+    end
+
+    # Make sheet name unique among existing sheets.
+    # If the name already exists, appends " (2)", " (3)", etc.
+    def deduplicate_sheet_name(name, max: SHEET_NAME_DEDUP_MAX)
+      existing = package.sheet_names
+      return name unless existing.include?(name)
+
+      counter = 2
+      loop do
+        suffix = " (#{counter})"
+        # Keep the deduplicated name within Excel's 31-character limit
+        base = name[0, MAX_SHEET_NAME_LENGTH - suffix.length]
+        candidate = "#{base}#{suffix}"
+        return candidate unless existing.include?(candidate)
+
+        counter += 1
+        if counter > max
+          raise LiquidXlsx::Error, "Could not find a unique name for sheet " \
+                                   "'#{name}' after #{max} attempts."
+        end
+      end
+    end
+
+    # Parse merge cell refs from the rendered worksheet XML for a given sheet_r_id.
+    # @return [Array<String>] e.g. ["A1:C2", "D5:D6"]
+    def sheet_merge_refs(sheet_r_id)
+      xml = package.worksheet_xml(sheet_r_id)
+      return [] unless xml
+
+      doc = Nokogiri::XML(xml)
+      ns = doc.root&.namespace
+      return [] unless ns
+
+      mc = doc.at_xpath("//xmlns:mergeCells", "xmlns" => ns.href)
+      return [] unless mc
+
+      mc.xpath("xmlns:mergeCell", "xmlns" => ns.href).map { |c| c["ref"] }
+    end
+  end
+end