fin_it 0.1.0

data/lib/fin_it/outputs/zaxcel_output.rb

@@ -0,0 +1,1264 @@
+# frozen_string_literal: true
+
+require 'zaxcel'
+
+module FinIt
+  module Outputs
+    class ZaxcelOutput < BaseOutput
+      def generate
+        @document = Zaxcel::Document.new
+        setup_styles
+
+        # Support multiple reports in one call
+        # Each report can be:
+        #   - A report object directly
+        #   - A hash with { report:, periods:, sheet_name: }
+        reports_to_process = options[:reports] || [@report]
+
+        reports_to_process.each do |report_data|
+          if report_data.is_a?(Hash) && report_data[:report]
+            @report = report_data[:report]
+            @current_sheet_name = report_data[:sheet_name]
+            original_periods = options[:periods]
+            options[:periods] = report_data[:periods] if report_data.key?(:periods)
+            process_report
+            options[:periods] = original_periods
+            @current_sheet_name = nil
+          else
+            @report = report_data
+            @current_sheet_name = nil
+            process_report
+          end
+        end
+
+        filename = options[:filename] || "report_#{@report.output_currency}.xlsx"
+        File.binwrite(filename, @document.file_contents)
+        filename
+      end
+
+      private
+
+      def setup_styles
+        # Required base styles for zaxcel
+        @document.add_style!(:default_cell)
+        @document.add_style!(:row_style)
+        @document.add_style!(:header_style, bg_color: 'E0E0E0', b: true)
+
+        # Custom styles for reports
+        @document.add_style!(:section_header, bg_color: 'F0F0F0', b: true)
+        @document.add_style!(:subtotal, bg_color: 'F5F5F5', b: true)
+        @document.add_style!(:total, bg_color: 'D0D0D0', b: true)
+        @document.add_style!(:currency, format_code: currency_format_code(@report.output_currency))
+        @document.add_style!(:currency_bold, format_code: currency_format_code(@report.output_currency), b: true)
+        @document.add_style!(:currency_total, format_code: currency_format_code(@report.output_currency), bg_color: 'D0D0D0', b: true)
+        @document.add_style!(:percent, format_code: '0.00%')
+      end
+
+      def currency_format_code(currency)
+        case currency
+        when 'USD' then '$#,##0.00'
+        when 'EUR' then '€#,##0.00'
+        when 'MXN' then 'MXN$#,##0.00'
+        when 'GBP' then '£#,##0.00'
+        else '#,##0.00'
+        end
+      end
+
+      def process_report
+        data = @report.generate
+        report_type = data[:report_type] || (data[:metadata] ? data[:metadata][:report_type] : nil)
+
+        # Handle special report types
+        case report_type
+        when "ScenarioComparison"
+          sheet_name = @current_sheet_name || "Scenario Comparison"
+          add_scenario_comparison(sheet_name, data)
+          return
+        when "PeriodComparison"
+          sheet_name = @current_sheet_name || "Period Comparison"
+          add_period_comparison(sheet_name, data)
+          return
+        when "CustomSheet"
+          sheet_name = @current_sheet_name || data[:title] || "Custom"
+          add_custom_sheet(sheet_name, data)
+          return
+        end
+
+        # Check if we have multiple periods to display as columns
+        periods_data = options[:periods]
+        if periods_data
+          periods_array = extract_periods_array(periods_data)
+
+          if periods_array && periods_array.length > 1
+            sheet_name = @current_sheet_name || generate_sheet_name(report_type, data[:project], 'Monthly')
+            case report_type
+            when "BalanceSheet"
+              add_balance_sheet_comparison(sheet_name, periods_array)
+            when "CashFlowStatement"
+              add_cash_flow_statement_comparison(sheet_name, periods_array, data)
+            else
+              add_income_statement_comparison(sheet_name, periods_array, data)
+            end
+            return
+          end
+        end
+
+        # Single period report
+        sheet_name = @current_sheet_name || generate_sheet_name(report_type, data[:project], nil)
+        case report_type
+        when "BalanceSheet"
+          add_balance_sheet(sheet_name, data)
+        when "CashFlowStatement"
+          add_cash_flow_statement(sheet_name, data)
+        else
+          add_income_statement(sheet_name, data)
+        end
+      end
+
+      def extract_periods_array(periods_data)
+        if periods_data.is_a?(Hash) && periods_data[:periods]
+          periods_data[:periods]
+        elsif periods_data.is_a?(Array)
+          periods_data
+        end
+      end
+
+      def generate_sheet_name(report_type, project, suffix)
+        parts = [report_type]
+        parts << project.to_s.split('_').map(&:capitalize).join(' ') if project
+        parts << suffix if suffix
+        name = parts.join(' - ')
+        name.length > 31 ? name[0..27] + '...' : name
+      end
+
+      # ==========================================
+      # Income Statement - Period Comparison
+      # ==========================================
+
+      def add_income_statement_comparison(sheet_name, periods, report_data)
+        sheet = @document.add_sheet!(sheet_name)
+        separate_cogs_mode = report_data[:expense_display_mode] == :separate_cogs
+        display_items = report_data[:display_items] || []
+
+        # Define columns: label + one per period
+        sheet.add_column!(:label, width: 50, row_style: :default_cell)
+        periods.each_with_index do |period_data, idx|
+          period = period_data[:period] || period_data[:report][:period]
+          header = period[:start].strftime('%b %Y')
+          sheet.add_column!(:"period_#{idx}", header: header, width: 15, row_style: :currency)
+        end
+
+        # Header row
+        sheet.add_column_header_row!
+
+        # Track row references for formulas
+        @row_refs = {}
+        row_counter = 0
+
+        # INCOME section
+        add_section_header(sheet, "INCOME", row_counter)
+        row_counter += 1
+
+        income_items = collect_items_from_periods(periods, :income)
+        row_counter = add_period_items(sheet, income_items, periods, row_counter, 0)
+
+        # TOTAL INCOME with SUM formula
+        total_income_row = sheet.add_row!(:"total_income_#{row_counter}")
+        total_income_row.add!(:label, value: 'TOTAL INCOME', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          income_total = report[:sections][:income][:total] rescue 0
+          total_income_row.add!(col, value: income_total, style: :currency_bold)
+        end
+        @row_refs[:total_income] = total_income_row
+        row_counter += 1
+
+        # Add empty row
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # COGS section if separate_cogs mode
+        if separate_cogs_mode
+          cogs_items = collect_items_from_periods(periods, :cogs)
+          if cogs_items.any?
+            add_section_header(sheet, "COST OF GOODS SOLD", row_counter)
+            row_counter += 1
+
+            row_counter = add_period_items(sheet, cogs_items, periods, row_counter, 0)
+
+            # TOTAL COGS
+            total_cogs_row = sheet.add_row!(:"total_cogs_#{row_counter}")
+            total_cogs_row.add!(:label, value: 'TOTAL COST OF GOODS SOLD', style: :subtotal)
+            periods.each_with_index do |period_data, idx|
+              col = :"period_#{idx}"
+              report = period_data[:report] || period_data
+              cogs_total = report[:sections][:cogs][:total] rescue 0
+              total_cogs_row.add!(col, value: cogs_total, style: :currency_bold)
+            end
+            @row_refs[:total_cogs] = total_cogs_row
+            row_counter += 1
+
+            # GROSS MARGIN with formula: TOTAL INCOME - TOTAL COGS
+            gross_margin_row = sheet.add_row!(:"gross_margin_#{row_counter}")
+            gross_margin_row.add!(:label, value: 'GROSS MARGIN', style: :total)
+            periods.each_with_index do |_, idx|
+              col = :"period_#{idx}"
+              income_ref = @row_refs[:total_income].ref(col)
+              cogs_ref = @row_refs[:total_cogs].ref(col)
+              gross_margin_row.add!(col, value: income_ref - cogs_ref, style: :currency_total)
+            end
+            @row_refs[:gross_margin] = gross_margin_row
+            row_counter += 1
+
+            sheet.add_empty_row!
+            row_counter += 1
+          end
+        end
+
+        # OPERATING EXPENSES section
+        section_label = separate_cogs_mode ? "OPERATING EXPENSES" : "EXPENSES"
+        add_section_header(sheet, section_label, row_counter)
+        row_counter += 1
+
+        expense_items = collect_items_from_periods(periods, :expenses)
+        row_counter = add_period_items(sheet, expense_items, periods, row_counter, 0)
+
+        # TOTAL EXPENSES
+        expense_total_label = separate_cogs_mode ? "TOTAL OPERATING EXPENSES" : "TOTAL EXPENSES"
+        total_expenses_row = sheet.add_row!(:"total_expenses_#{row_counter}")
+        total_expenses_row.add!(:label, value: expense_total_label, style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          expense_total = report[:sections][:expenses][:total] rescue 0
+          total_expenses_row.add!(col, value: expense_total, style: :currency_bold)
+        end
+        @row_refs[:total_expenses] = total_expenses_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # NET INCOME with formula: TOTAL INCOME - TOTAL EXPENSES (or GROSS MARGIN - TOTAL EXPENSES)
+        net_income_row = sheet.add_row!(:"net_income_#{row_counter}")
+        net_income_row.add!(:label, value: 'NET INCOME', style: :total)
+        periods.each_with_index do |_, idx|
+          col = :"period_#{idx}"
+          if separate_cogs_mode && @row_refs[:gross_margin]
+            gross_margin_ref = @row_refs[:gross_margin].ref(col)
+            expenses_ref = @row_refs[:total_expenses].ref(col)
+            net_income_row.add!(col, value: gross_margin_ref - expenses_ref, style: :currency_total)
+          else
+            income_ref = @row_refs[:total_income].ref(col)
+            expenses_ref = @row_refs[:total_expenses].ref(col)
+            net_income_row.add!(col, value: income_ref - expenses_ref, style: :currency_total)
+          end
+        end
+        @row_refs[:net_income] = net_income_row
+        row_counter += 1
+
+        # Add display items (like Net Margin %)
+        display_items.select { |di| di[:after] == :net_income }.each do |item|
+          display_row = sheet.add_row!(:"display_#{item[:name]}_#{row_counter}")
+          display_row.add!(:label, value: item[:label])
+
+          periods.each_with_index do |period_data, idx|
+            col = :"period_#{idx}"
+            report = period_data[:report] || period_data
+            period_items = report[:display_items] || []
+            period_item = period_items.find { |di| di[:name] == item[:name] }
+            value = period_item ? period_item[:value] : 0
+
+            style = item[:format] == :percentage ? :percent : :currency
+            formatted_value = item[:format] == :percentage ? value / 100.0 : value
+            display_row.add!(col, value: formatted_value, style: style)
+          end
+          row_counter += 1
+        end
+
+        # Position and generate
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      def collect_items_from_periods(periods, section_key)
+        items = {}
+        periods.each_with_index do |period_data, idx|
+          report = period_data[:report] || period_data
+          section = report[:sections][section_key] rescue nil
+          next unless section && section[:items]
+
+          section[:items].each do |item|
+            collect_item_recursive(items, item, idx)
+          end
+        end
+        items
+      end
+
+      def collect_item_recursive(items, item, period_idx)
+        key = item[:name] || item[:display_name]
+        display_name = item[:display_name] || humanize_name(key)
+        indent = item[:indent] || 0
+
+        items[key] ||= {
+          name: key,
+          display_name: display_name,
+          indent: indent,
+          values: {},
+          subcategories: {}
+        }
+
+        items[key][:values][period_idx] = item[:value] || 0
+
+        if item[:subcategories]
+          item[:subcategories].each do |sub|
+            collect_item_recursive(items[key][:subcategories], sub, period_idx)
+          end
+        end
+      end
+
+      def add_period_items(sheet, items, periods, row_counter, indent_level)
+        items.each do |key, item_data|
+          indent = "  " * (indent_level + item_data[:indent])
+          row_name = :"item_#{key}_#{row_counter}"
+          row = sheet.add_row!(row_name)
+          row.add!(:label, value: "#{indent}#{item_data[:display_name]}")
+
+          periods.each_with_index do |_, idx|
+            col = :"period_#{idx}"
+            value = item_data[:values][idx] || 0
+            row.add!(col, value: value, style: :currency)
+          end
+
+          row_counter += 1
+
+          # Add subcategories
+          if item_data[:subcategories] && item_data[:subcategories].any?
+            row_counter = add_period_items(sheet, item_data[:subcategories], periods, row_counter, indent_level + 1)
+          end
+        end
+
+        row_counter
+      end
+
+      def add_section_header(sheet, label, row_counter)
+        row = sheet.add_row!(:"section_#{label.downcase.gsub(' ', '_')}_#{row_counter}")
+        row.add!(:label, value: label, style: :section_header)
+      end
+
+      # ==========================================
+      # Single Period Income Statement
+      # ==========================================
+
+      def add_income_statement(sheet_name, data)
+        sheet = @document.add_sheet!(sheet_name)
+
+        sheet.add_column!(:label, width: 50, row_style: :default_cell)
+        sheet.add_column!(:value, header: data[:currency], width: 20, row_style: :currency)
+
+        sheet.add_column_header_row!
+
+        row_counter = 0
+
+        # INCOME section
+        if data[:sections][:income]
+          add_section_header(sheet, "INCOME", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, data[:sections][:income][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_income_#{row_counter}")
+          total_row.add!(:label, value: 'TOTAL INCOME', style: :subtotal)
+          total_row.add!(:value, value: data[:sections][:income][:total] || 0, style: :currency_bold)
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # EXPENSES section
+        if data[:sections][:expenses]
+          add_section_header(sheet, "EXPENSES", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, data[:sections][:expenses][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_expenses_#{row_counter}")
+          total_row.add!(:label, value: 'TOTAL EXPENSES', style: :subtotal)
+          total_row.add!(:value, value: data[:sections][:expenses][:total] || 0, style: :currency_bold)
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # NET INCOME
+        net_income_row = sheet.add_row!(:"net_income_#{row_counter}")
+        net_income_row.add!(:label, value: 'NET INCOME', style: :total)
+        net_income = (data[:sections][:income][:total] || 0) - (data[:sections][:expenses][:total] || 0)
+        net_income_row.add!(:value, value: net_income, style: :currency_total)
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      def add_single_period_items(sheet, items, row_counter, indent_level)
+        return row_counter unless items
+
+        items.each do |item|
+          indent = "  " * (indent_level + (item[:indent] || 0))
+          row = sheet.add_row!(:"item_#{row_counter}")
+          row.add!(:label, value: "#{indent}#{item[:display_name] || humanize_name(item[:name])}")
+          row.add!(:value, value: item[:value] || 0, style: :currency)
+          row_counter += 1
+
+          if item[:subcategories]
+            row_counter = add_single_period_items(sheet, item[:subcategories], row_counter, indent_level + 1)
+          end
+        end
+
+        row_counter
+      end
+
+      # ==========================================
+      # Balance Sheet
+      # ==========================================
+
+      def add_balance_sheet(sheet_name, data)
+        sheet = @document.add_sheet!(sheet_name)
+
+        sheet.add_column!(:label, width: 50, row_style: :default_cell)
+        sheet.add_column!(:value, header: data[:currency], width: 20, row_style: :currency)
+
+        sheet.add_column_header_row!
+
+        row_counter = 0
+        @row_refs = {}
+
+        # ASSETS section
+        if data[:sections][:assets]
+          add_section_header(sheet, "ASSETS", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, data[:sections][:assets][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_assets_#{row_counter}")
+          total_row.add!(:label, value: 'TOTAL ASSETS', style: :total)
+          total_row.add!(:value, value: data[:sections][:total_assets][:total] || 0, style: :currency_total)
+          @row_refs[:total_assets] = total_row
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # LIABILITIES section
+        add_section_header(sheet, "LIABILITIES", row_counter)
+        row_counter += 1
+        if data[:sections][:liabilities] && data[:sections][:liabilities][:items]
+          row_counter = add_single_period_items(sheet, data[:sections][:liabilities][:items], row_counter, 0)
+        end
+
+        total_liabilities_row = sheet.add_row!(:"total_liabilities_#{row_counter}")
+        total_liabilities_row.add!(:label, value: 'TOTAL LIABILITIES', style: :subtotal)
+        total_liabilities_row.add!(:value, value: data[:sections][:total_liabilities][:total] || 0, style: :currency_bold)
+        @row_refs[:total_liabilities] = total_liabilities_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # EQUITY section
+        add_section_header(sheet, "EQUITY", row_counter)
+        row_counter += 1
+        if data[:sections][:equity] && data[:sections][:equity][:items]
+          row_counter = add_single_period_items(sheet, data[:sections][:equity][:items], row_counter, 0)
+        end
+
+        # Accumulated net income
+        if data[:sections][:accumulated_net_income] && data[:sections][:accumulated_net_income][:items]
+          row_counter = add_single_period_items(sheet, data[:sections][:accumulated_net_income][:items], row_counter, 0)
+        end
+
+        total_equity_row = sheet.add_row!(:"total_equity_#{row_counter}")
+        total_equity_row.add!(:label, value: 'TOTAL EQUITY', style: :subtotal)
+        total_equity_row.add!(:value, value: (data[:sections][:equity][:total] || 0) + (data[:sections][:accumulated_net_income][:total] || 0), style: :currency_bold)
+        @row_refs[:total_equity] = total_equity_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # TOTAL LIABILITIES AND EQUITY with formula
+        total_le_row = sheet.add_row!(:"total_le_#{row_counter}")
+        total_le_row.add!(:label, value: 'TOTAL LIABILITIES AND EQUITY', style: :total)
+        liabilities_ref = @row_refs[:total_liabilities].ref(:value)
+        equity_ref = @row_refs[:total_equity].ref(:value)
+        total_le_row.add!(:value, value: liabilities_ref + equity_ref, style: :currency_total)
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      def add_balance_sheet_comparison(sheet_name, periods)
+        sheet = @document.add_sheet!(sheet_name)
+
+        # Define columns
+        sheet.add_column!(:label, width: 50, row_style: :default_cell)
+        periods.each_with_index do |period_data, idx|
+          period = period_data[:period] || period_data[:report][:period]
+          header = period[:end].strftime('%b %Y')
+          sheet.add_column!(:"period_#{idx}", header: header, width: 15, row_style: :currency)
+        end
+
+        sheet.add_column_header_row!
+
+        row_counter = 0
+        @row_refs = {}
+
+        # ASSETS section
+        add_section_header(sheet, "ASSETS", row_counter)
+        row_counter += 1
+
+        asset_items = collect_items_from_periods(periods, :assets)
+        row_counter = add_period_items(sheet, asset_items, periods, row_counter, 0)
+
+        total_assets_row = sheet.add_row!(:"total_assets_#{row_counter}")
+        total_assets_row.add!(:label, value: 'TOTAL ASSETS', style: :total)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          total = report[:sections][:total_assets][:total] rescue 0
+          total_assets_row.add!(col, value: total, style: :currency_total)
+        end
+        @row_refs[:total_assets] = total_assets_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # LIABILITIES section
+        add_section_header(sheet, "LIABILITIES", row_counter)
+        row_counter += 1
+
+        liability_items = collect_items_from_periods(periods, :liabilities)
+        row_counter = add_period_items(sheet, liability_items, periods, row_counter, 0)
+
+        total_liabilities_row = sheet.add_row!(:"total_liabilities_#{row_counter}")
+        total_liabilities_row.add!(:label, value: 'TOTAL LIABILITIES', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          total = report[:sections][:total_liabilities][:total] rescue 0
+          total_liabilities_row.add!(col, value: total, style: :currency_bold)
+        end
+        @row_refs[:total_liabilities] = total_liabilities_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # EQUITY section
+        add_section_header(sheet, "EQUITY", row_counter)
+        row_counter += 1
+
+        equity_items = collect_items_from_periods(periods, :equity)
+        row_counter = add_period_items(sheet, equity_items, periods, row_counter, 0)
+
+        # Accumulated net income
+        acc_net_items = collect_items_from_periods(periods, :accumulated_net_income)
+        row_counter = add_period_items(sheet, acc_net_items, periods, row_counter, 0)
+
+        total_equity_row = sheet.add_row!(:"total_equity_#{row_counter}")
+        total_equity_row.add!(:label, value: 'TOTAL EQUITY', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          equity_total = report[:sections][:equity][:total] rescue 0
+          acc_net = report[:sections][:accumulated_net_income][:total] rescue 0
+          total_equity_row.add!(col, value: equity_total + acc_net, style: :currency_bold)
+        end
+        @row_refs[:total_equity] = total_equity_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # TOTAL LIABILITIES AND EQUITY with formula
+        total_le_row = sheet.add_row!(:"total_le_#{row_counter}")
+        total_le_row.add!(:label, value: 'TOTAL LIABILITIES AND EQUITY', style: :total)
+        periods.each_with_index do |_, idx|
+          col = :"period_#{idx}"
+          liab_ref = @row_refs[:total_liabilities].ref(col)
+          equity_ref = @row_refs[:total_equity].ref(col)
+          total_le_row.add!(col, value: liab_ref + equity_ref, style: :currency_total)
+        end
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      def humanize_name(name)
+        name.to_s.split('_').map(&:capitalize).join(' ')
+      end
+
+      # ==========================================
+      # Cash Flow Statement
+      # ==========================================
+
+      def add_cash_flow_statement(sheet_name, data)
+        sheet = @document.add_sheet!(sheet_name)
+
+        sheet.add_column!(:label, width: 50, row_style: :default_cell)
+        sheet.add_column!(:value, header: data[:currency], width: 20, row_style: :currency)
+
+        sheet.add_column_header_row!
+
+        row_counter = 0
+        @row_refs = {}
+        display_mode = data[:display_mode] || :standard
+
+        if display_mode == :simple
+          row_counter = add_simple_cash_flow(sheet, data, row_counter)
+        else
+          row_counter = add_standard_cash_flow(sheet, data, row_counter)
+        end
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      def add_standard_cash_flow(sheet, data, row_counter)
+        sections = data[:sections] || {}
+
+        # OPERATING ACTIVITIES
+        if sections[:operating]
+          add_section_header(sheet, "OPERATING ACTIVITIES", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, sections[:operating][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_operating_#{row_counter}")
+          total_row.add!(:label, value: 'Net Cash from Operating Activities', style: :subtotal)
+          total_row.add!(:value, value: sections[:operating][:total] || 0, style: :currency_bold)
+          @row_refs[:total_operating] = total_row
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # INVESTING ACTIVITIES
+        if sections[:investing]
+          add_section_header(sheet, "INVESTING ACTIVITIES", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, sections[:investing][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_investing_#{row_counter}")
+          total_row.add!(:label, value: 'Net Cash from Investing Activities', style: :subtotal)
+          total_row.add!(:value, value: sections[:investing][:total] || 0, style: :currency_bold)
+          @row_refs[:total_investing] = total_row
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # FINANCING ACTIVITIES
+        if sections[:financing]
+          add_section_header(sheet, "FINANCING ACTIVITIES", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, sections[:financing][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_financing_#{row_counter}")
+          total_row.add!(:label, value: 'Net Cash from Financing Activities', style: :subtotal)
+          total_row.add!(:value, value: sections[:financing][:total] || 0, style: :currency_bold)
+          @row_refs[:total_financing] = total_row
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # NET CHANGE IN CASH
+        net_change_row = sheet.add_row!(:"net_change_#{row_counter}")
+        net_change_row.add!(:label, value: 'NET CHANGE IN CASH', style: :total)
+        net_change_row.add!(:value, value: sections[:net_change_in_cash][:total] || 0, style: :currency_total)
+        @row_refs[:net_change] = net_change_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # BEGINNING CASH BALANCE
+        beginning_row = sheet.add_row!(:"beginning_cash_#{row_counter}")
+        beginning_row.add!(:label, value: 'Beginning Cash Balance')
+        beginning_row.add!(:value, value: sections[:beginning_cash][:total] || 0, style: :currency)
+        @row_refs[:beginning_cash] = beginning_row
+        row_counter += 1
+
+        # ENDING CASH BALANCE
+        ending_row = sheet.add_row!(:"ending_cash_#{row_counter}")
+        ending_row.add!(:label, value: 'ENDING CASH BALANCE', style: :total)
+        ending_row.add!(:value, value: sections[:ending_cash][:total] || 0, style: :currency_total)
+        row_counter += 1
+
+        row_counter
+      end
+
+      def add_simple_cash_flow(sheet, data, row_counter)
+        sections = data[:sections] || {}
+
+        # CASH INFLOWS
+        if sections[:cash_in]
+          add_section_header(sheet, "CASH INFLOWS", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, sections[:cash_in][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_cash_in_#{row_counter}")
+          total_row.add!(:label, value: 'TOTAL CASH INFLOWS', style: :subtotal)
+          total_row.add!(:value, value: sections[:cash_in][:total] || 0, style: :currency_bold)
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # CASH OUTFLOWS
+        if sections[:cash_out]
+          add_section_header(sheet, "CASH OUTFLOWS", row_counter)
+          row_counter += 1
+          row_counter = add_single_period_items(sheet, sections[:cash_out][:items], row_counter, 0)
+
+          total_row = sheet.add_row!(:"total_cash_out_#{row_counter}")
+          total_row.add!(:label, value: 'TOTAL CASH OUTFLOWS', style: :subtotal)
+          total_row.add!(:value, value: sections[:cash_out][:total] || 0, style: :currency_bold)
+          row_counter += 1
+        end
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # NET CHANGE IN CASH
+        net_change_row = sheet.add_row!(:"net_change_#{row_counter}")
+        net_change_row.add!(:label, value: 'NET CHANGE IN CASH', style: :total)
+        net_change_row.add!(:value, value: sections[:net_change_in_cash][:total] || 0, style: :currency_total)
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # BEGINNING AND ENDING CASH
+        beginning_row = sheet.add_row!(:"beginning_cash_#{row_counter}")
+        beginning_row.add!(:label, value: 'Beginning Cash Balance')
+        beginning_row.add!(:value, value: sections[:beginning_cash][:total] || 0, style: :currency)
+        row_counter += 1
+
+        ending_row = sheet.add_row!(:"ending_cash_#{row_counter}")
+        ending_row.add!(:label, value: 'ENDING CASH BALANCE', style: :total)
+        ending_row.add!(:value, value: sections[:ending_cash][:total] || 0, style: :currency_total)
+        row_counter += 1
+
+        row_counter
+      end
+
+      def add_cash_flow_statement_comparison(sheet_name, periods, report_data)
+        sheet = @document.add_sheet!(sheet_name)
+        display_mode = report_data[:display_mode] || :standard
+
+        # Define columns: label + one per period
+        sheet.add_column!(:label, width: 50, row_style: :default_cell)
+        periods.each_with_index do |period_data, idx|
+          period = period_data[:period] || period_data[:report][:period]
+          header = period[:start].strftime('%b %Y')
+          sheet.add_column!(:"period_#{idx}", header: header, width: 15, row_style: :currency)
+        end
+
+        sheet.add_column_header_row!
+
+        @row_refs = {}
+        row_counter = 0
+
+        if display_mode == :simple
+          row_counter = add_simple_cash_flow_comparison(sheet, periods, row_counter)
+        else
+          row_counter = add_standard_cash_flow_comparison(sheet, periods, row_counter)
+        end
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      def add_standard_cash_flow_comparison(sheet, periods, row_counter)
+        # OPERATING ACTIVITIES
+        add_section_header(sheet, "OPERATING ACTIVITIES", row_counter)
+        row_counter += 1
+
+        operating_items = collect_items_from_periods(periods, :operating)
+        row_counter = add_period_items(sheet, operating_items, periods, row_counter, 0)
+
+        total_operating_row = sheet.add_row!(:"total_operating_#{row_counter}")
+        total_operating_row.add!(:label, value: 'Net Cash from Operating Activities', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          total = report[:sections][:operating][:total] rescue 0
+          total_operating_row.add!(col, value: total, style: :currency_bold)
+        end
+        @row_refs[:total_operating] = total_operating_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # INVESTING ACTIVITIES
+        add_section_header(sheet, "INVESTING ACTIVITIES", row_counter)
+        row_counter += 1
+
+        investing_items = collect_items_from_periods(periods, :investing)
+        row_counter = add_period_items(sheet, investing_items, periods, row_counter, 0)
+
+        total_investing_row = sheet.add_row!(:"total_investing_#{row_counter}")
+        total_investing_row.add!(:label, value: 'Net Cash from Investing Activities', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          total = report[:sections][:investing][:total] rescue 0
+          total_investing_row.add!(col, value: total, style: :currency_bold)
+        end
+        @row_refs[:total_investing] = total_investing_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # FINANCING ACTIVITIES
+        add_section_header(sheet, "FINANCING ACTIVITIES", row_counter)
+        row_counter += 1
+
+        financing_items = collect_items_from_periods(periods, :financing)
+        row_counter = add_period_items(sheet, financing_items, periods, row_counter, 0)
+
+        total_financing_row = sheet.add_row!(:"total_financing_#{row_counter}")
+        total_financing_row.add!(:label, value: 'Net Cash from Financing Activities', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          total = report[:sections][:financing][:total] rescue 0
+          total_financing_row.add!(col, value: total, style: :currency_bold)
+        end
+        @row_refs[:total_financing] = total_financing_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # NET CHANGE IN CASH with formula
+        net_change_row = sheet.add_row!(:"net_change_#{row_counter}")
+        net_change_row.add!(:label, value: 'NET CHANGE IN CASH', style: :total)
+        periods.each_with_index do |_, idx|
+          col = :"period_#{idx}"
+          operating_ref = @row_refs[:total_operating].ref(col)
+          investing_ref = @row_refs[:total_investing].ref(col)
+          financing_ref = @row_refs[:total_financing].ref(col)
+          net_change_row.add!(col, value: operating_ref + investing_ref + financing_ref, style: :currency_total)
+        end
+        @row_refs[:net_change] = net_change_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # BEGINNING CASH BALANCE
+        beginning_row = sheet.add_row!(:"beginning_cash_#{row_counter}")
+        beginning_row.add!(:label, value: 'Beginning Cash Balance')
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          beginning = report[:sections][:beginning_cash][:total] rescue 0
+          beginning_row.add!(col, value: beginning, style: :currency)
+        end
+        @row_refs[:beginning_cash] = beginning_row
+        row_counter += 1
+
+        # ENDING CASH BALANCE with formula
+        ending_row = sheet.add_row!(:"ending_cash_#{row_counter}")
+        ending_row.add!(:label, value: 'ENDING CASH BALANCE', style: :total)
+        periods.each_with_index do |_, idx|
+          col = :"period_#{idx}"
+          beginning_ref = @row_refs[:beginning_cash].ref(col)
+          net_change_ref = @row_refs[:net_change].ref(col)
+          ending_row.add!(col, value: beginning_ref + net_change_ref, style: :currency_total)
+        end
+        row_counter += 1
+
+        row_counter
+      end
+
+      def add_simple_cash_flow_comparison(sheet, periods, row_counter)
+        # CASH INFLOWS
+        add_section_header(sheet, "CASH INFLOWS", row_counter)
+        row_counter += 1
+
+        cash_in_items = collect_items_from_periods(periods, :cash_in)
+        row_counter = add_period_items(sheet, cash_in_items, periods, row_counter, 0)
+
+        total_in_row = sheet.add_row!(:"total_cash_in_#{row_counter}")
+        total_in_row.add!(:label, value: 'TOTAL CASH INFLOWS', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          total = report[:sections][:cash_in][:total] rescue 0
+          total_in_row.add!(col, value: total, style: :currency_bold)
+        end
+        @row_refs[:total_cash_in] = total_in_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # CASH OUTFLOWS
+        add_section_header(sheet, "CASH OUTFLOWS", row_counter)
+        row_counter += 1
+
+        cash_out_items = collect_items_from_periods(periods, :cash_out)
+        row_counter = add_period_items(sheet, cash_out_items, periods, row_counter, 0)
+
+        total_out_row = sheet.add_row!(:"total_cash_out_#{row_counter}")
+        total_out_row.add!(:label, value: 'TOTAL CASH OUTFLOWS', style: :subtotal)
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          total = report[:sections][:cash_out][:total] rescue 0
+          total_out_row.add!(col, value: total, style: :currency_bold)
+        end
+        @row_refs[:total_cash_out] = total_out_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # NET CHANGE IN CASH with formula
+        net_change_row = sheet.add_row!(:"net_change_#{row_counter}")
+        net_change_row.add!(:label, value: 'NET CHANGE IN CASH', style: :total)
+        periods.each_with_index do |_, idx|
+          col = :"period_#{idx}"
+          in_ref = @row_refs[:total_cash_in].ref(col)
+          out_ref = @row_refs[:total_cash_out].ref(col)
+          net_change_row.add!(col, value: in_ref - out_ref, style: :currency_total)
+        end
+        @row_refs[:net_change] = net_change_row
+        row_counter += 1
+
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # BEGINNING AND ENDING CASH
+        beginning_row = sheet.add_row!(:"beginning_cash_#{row_counter}")
+        beginning_row.add!(:label, value: 'Beginning Cash Balance')
+        periods.each_with_index do |period_data, idx|
+          col = :"period_#{idx}"
+          report = period_data[:report] || period_data
+          beginning = report[:sections][:beginning_cash][:total] rescue 0
+          beginning_row.add!(col, value: beginning, style: :currency)
+        end
+        @row_refs[:beginning_cash] = beginning_row
+        row_counter += 1
+
+        ending_row = sheet.add_row!(:"ending_cash_#{row_counter}")
+        ending_row.add!(:label, value: 'ENDING CASH BALANCE', style: :total)
+        periods.each_with_index do |_, idx|
+          col = :"period_#{idx}"
+          beginning_ref = @row_refs[:beginning_cash].ref(col)
+          net_change_ref = @row_refs[:net_change].ref(col)
+          ending_row.add!(col, value: beginning_ref + net_change_ref, style: :currency_total)
+        end
+        row_counter += 1
+
+        row_counter
+      end
+
+      # ==========================================
+      # Scenario Comparison
+      # ==========================================
+
+      def add_scenario_comparison(sheet_name, data)
+        sheet = @document.add_sheet!(sheet_name)
+
+        metadata = data[:metadata]
+        base_metrics = data[:base]
+        scenarios = data[:scenarios]
+        variances = data[:variances]
+        scenario_names = metadata[:scenario_names]
+
+        # Define columns: label + base + one per scenario + variances
+        sheet.add_column!(:metric, header: 'Metric', width: 30, row_style: :default_cell)
+        sheet.add_column!(:base, header: 'Base', width: 18, row_style: :currency)
+
+        scenario_names.each_with_index do |name, idx|
+          sheet.add_column!(:"scenario_#{idx}", header: humanize_name(name), width: 18, row_style: :currency)
+          sheet.add_column!(:"variance_#{idx}", header: "Var %", width: 12, row_style: :percent)
+        end
+
+        sheet.add_column_header_row!
+
+        # Title row
+        title_row = sheet.add_row!(:title)
+        title_row.add!(:metric, value: "SCENARIO COMPARISON", style: :section_header)
+        sheet.add_empty_row!
+
+        # Period info
+        period_row = sheet.add_row!(:period_info)
+        period_row.add!(:metric, value: "Period: #{metadata[:start_date]} to #{metadata[:end_date]}")
+        sheet.add_empty_row!
+
+        # Use normalized_metrics if available (has labels)
+        normalized_metrics = metadata[:normalized_metrics] || []
+
+        # Add each metric
+        normalized_metrics.each_with_index do |metric_config, metric_idx|
+          metric_key = metric_config[:key]
+          metric_label = metric_config[:label]
+          base_value = base_metrics[metric_key] || 0
+
+          row = sheet.add_row!(:"metric_#{metric_idx}")
+          row.add!(:metric, value: metric_label, style: :default_cell)
+          row.add!(:base, value: base_value, style: :currency_bold)
+
+          scenario_names.each_with_index do |scenario_name, idx|
+            scenario_metrics = scenarios[scenario_name]
+            scenario_value = scenario_metrics ? (scenario_metrics[metric_key] || 0) : 0
+            row.add!(:"scenario_#{idx}", value: scenario_value, style: :currency)
+
+            # Variance percentage
+            if variances[scenario_name]
+              metric_variance = variances[scenario_name][metric_key]
+              if metric_variance
+                pct = metric_variance[:percentage] / 100.0  # Convert to decimal for Excel
+                row.add!(:"variance_#{idx}", value: pct, style: :percent)
+              else
+                row.add!(:"variance_#{idx}", value: 0, style: :percent)
+              end
+            else
+              row.add!(:"variance_#{idx}", value: 0, style: :percent)
+            end
+          end
+        end
+
+        sheet.add_empty_row!
+
+        # Generated timestamp
+        timestamp_row = sheet.add_row!(:timestamp)
+        timestamp_row.add!(:metric, value: "Generated: #{metadata[:generated_at]}")
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      # ==========================================
+      # Period Comparison
+      # ==========================================
+
+      def add_period_comparison(sheet_name, data)
+        sheet = @document.add_sheet!(sheet_name)
+
+        metadata = data[:metadata]
+        periods = data[:periods]
+        variances = data[:variances]
+        normalized_metrics = metadata[:normalized_metrics] || []
+
+        # Define columns: metric + one per period with variance
+        sheet.add_column!(:metric, header: 'Metric', width: 30, row_style: :default_cell)
+
+        periods.each_with_index do |period, idx|
+          sheet.add_column!(:"period_#{idx}", header: period[:name], width: 18, row_style: :currency)
+          sheet.add_column!(:"variance_#{idx}", header: "Var %", width: 12, row_style: :percent) unless idx == 0
+        end
+
+        sheet.add_column_header_row!
+
+        # Title row
+        title_row = sheet.add_row!(:title)
+        title_row.add!(:metric, value: "PERIOD COMPARISON", style: :section_header)
+        sheet.add_empty_row!
+
+        # Add each metric
+        normalized_metrics.each_with_index do |metric_config, metric_idx|
+          metric_key = metric_config[:variable]
+          metric_label = metric_config[:label]
+
+          row = sheet.add_row!(:"metric_#{metric_idx}")
+          row.add!(:metric, value: metric_label, style: :default_cell)
+
+          periods.each_with_index do |period, idx|
+            period_value = period[:metrics][metric_key] || 0
+            row.add!(:"period_#{idx}", value: period_value, style: :currency_bold)
+
+            # Variance percentage (skip first period)
+            unless idx == 0
+              var_data = variances[idx]
+              if var_data && var_data[:variances]
+                metric_variance = var_data[:variances][metric_key]
+                if metric_variance
+                  pct = metric_variance[:percentage] / 100.0
+                  row.add!(:"variance_#{idx}", value: pct, style: :percent)
+                else
+                  row.add!(:"variance_#{idx}", value: 0, style: :percent)
+                end
+              else
+                row.add!(:"variance_#{idx}", value: 0, style: :percent)
+              end
+            end
+          end
+        end
+
+        sheet.add_empty_row!
+
+        # Generated timestamp
+        timestamp_row = sheet.add_row!(:timestamp)
+        timestamp_row.add!(:metric, value: "Generated: #{metadata[:generated_at]}")
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      # ==========================================
+      # Custom Sheet
+      # ==========================================
+
+      def add_custom_sheet(sheet_name, data)
+        sheet = @document.add_sheet!(sheet_name)
+
+        # Add custom styles for custom sheet
+        @document.add_style!(:title_large, b: true, sz: 18) rescue nil
+        @document.add_style!(:header_medium, b: true, sz: 14) rescue nil
+        @document.add_style!(:header_small, b: true, sz: 12) rescue nil
+        @document.add_style!(:paragraph_style, wrap_text: true) rescue nil
+        @document.add_style!(:table_header_style, b: true, bg_color: 'E0E0E0') rescue nil
+
+        # Use wider main column
+        sheet.add_column!(:main, width: 80, row_style: :default_cell)
+
+        title = data[:title]
+        sections = data[:sections]
+
+        row_counter = 0
+
+        # Title
+        title_row = sheet.add_row!(:"row_#{row_counter}")
+        title_row.add!(:main, value: title, style: :title_large)
+        row_counter += 1
+        sheet.add_empty_row!
+        row_counter += 1
+
+        # Process sections
+        sections.each do |section|
+          case section[:type]
+          when :header
+            level = section[:level] || 1
+            style = case level
+                    when 1 then :title_large
+                    when 2 then :header_medium
+                    else :header_small
+                    end
+            row = sheet.add_row!(:"row_#{row_counter}")
+            row.add!(:main, value: section[:text], style: style)
+            row_counter += 1
+
+          when :paragraph
+            row = sheet.add_row!(:"row_#{row_counter}")
+            row.add!(:main, value: section[:text], style: :paragraph_style)
+            row_counter += 1
+
+          when :spacer
+            (section[:rows] || 1).times do
+              sheet.add_empty_row!
+              row_counter += 1
+            end
+
+          when :key_value
+            row = sheet.add_row!(:"row_#{row_counter}")
+            row.add!(:main, value: "#{section[:label]}: #{section[:value]}")
+            row_counter += 1
+
+          when :bullet_list
+            section[:items].each do |item|
+              row = sheet.add_row!(:"row_#{row_counter}")
+              row.add!(:main, value: "  \u2022 #{item}")
+              row_counter += 1
+            end
+
+          when :numbered_list
+            section[:items].each_with_index do |item, idx|
+              row = sheet.add_row!(:"row_#{row_counter}")
+              row.add!(:main, value: "  #{idx + 1}. #{item}")
+              row_counter += 1
+            end
+
+          when :table
+            row_counter = add_custom_sheet_inline_table(sheet, section, row_counter)
+
+          when :hr
+            row = sheet.add_row!(:"row_#{row_counter}")
+            row.add!(:main, value: "\u2500" * 50)
+            row_counter += 1
+
+          when :note
+            prefix = case section[:style]
+                     when :warning then "[!] "
+                     when :error then "[X] "
+                     when :success then "[+] "
+                     else "[i] "
+                     end
+            row = sheet.add_row!(:"row_#{row_counter}")
+            row.add!(:main, value: "#{prefix}#{section[:text]}")
+            row_counter += 1
+          end
+        end
+
+        # Generated timestamp if present
+        if data[:generated_at]
+          sheet.add_empty_row!
+          row_counter += 1
+          timestamp_row = sheet.add_row!(:"row_#{row_counter}")
+          timestamp_row.add!(:main, value: "Generated: #{data[:generated_at]}")
+        end
+
+        sheet.position_rows!
+        sheet.generate_sheet!
+      end
+
+      def add_custom_sheet_inline_table(sheet, section, start_row)
+        headers = section[:headers]
+        rows = section[:rows]
+        row_counter = start_row
+
+        # Add title if present
+        if section[:title]
+          title_row = sheet.add_row!(:"row_#{row_counter}")
+          title_row.add!(:main, value: section[:title], style: :header_small)
+          row_counter += 1
+        end
+
+        # For inline tables, we format as text in the main column
+        # Build formatted header row
+        header_text = headers.join(" | ")
+        header_row = sheet.add_row!(:"row_#{row_counter}")
+        header_row.add!(:main, value: header_text, style: :table_header_style)
+        row_counter += 1
+
+        # Separator
+        sep_row = sheet.add_row!(:"row_#{row_counter}")
+        sep_row.add!(:main, value: "-" * header_text.length)
+        row_counter += 1
+
+        # Data rows
+        rows.each do |row_data|
+          data_text = row_data.join(" | ")
+          data_row = sheet.add_row!(:"row_#{row_counter}")
+          data_row.add!(:main, value: data_text)
+          row_counter += 1
+        end
+
+        row_counter
+      end
+    end
+  end
+end