Follow correct mental model in examples/docs: position and generate after all content is added

Author: chamod-gamage

QUICK_START.md

@@ -34,7 +34,8 @@ sheet.add_row!(:person2)
   .add!(:name, value: 'Bob')
   .add!(:age, value: 25)
 
-# Generate and save
+# Position and generate sheet (after all content is added)
+sheet.position_rows!
 sheet.generate_sheet!
 File.write('people.xlsx', document.file_contents)
 
@@ -72,6 +73,8 @@ sheet.add_row!(:total)
   .add!(:label, value: 'Total')
   .add!(:value, row1.ref(:value) + row2.ref(:value))
 
+# Position and generate sheet (after all content is added)
+sheet.position_rows!
 sheet.generate_sheet!
 File.write('math.xlsx', document.file_contents)
 ```
@@ -103,6 +106,8 @@ sheet.add_row!(:header)
 sheet.add_row!(:data)
   .add!(:category, value: 'Data')
 
+# Position and generate sheet (after all content is added)
+sheet.position_rows!
 sheet.generate_sheet!
 File.write('styled.xlsx', document.file_contents)
 ```
@@ -148,6 +153,8 @@ data.each_with_index do |item, i|
     .add!(:amount, value: item[:amount])
 end
 
+# Position and generate sheet (after all content is added)
+sheet.position_rows!
 sheet.generate_sheet!
 ```
 
@@ -178,4 +185,3 @@ rounded = Zaxcel::Functions.round(value, precision: 2)
 - Open an issue on GitHub
 
 Happy spreadsheet building! 📊
-

README.md

@@ -72,7 +72,7 @@ sheet.add_row!(:total)
   .add!(:column_1, value: 'Total')
   .add!(:column_2, row_1.ref(:column_2) + row_2.ref(:column_2))
 
-# Finalize the sheet (position rows before generating so references resolve)
+# Finalize the sheet (position and generate after all content is added)
 sheet.position_rows!
 sheet.generate_sheet!
 
@@ -133,10 +133,6 @@ row_1 = data_sheet.add_row!(:row_1)
   .add!(:category, value: 'Sales')
   .add!(:value, value: 1000)
 
-# Prepare the data sheet so other sheets can reference it
-data_sheet.position_rows!
-data_sheet.generate_sheet!
-
 # Create summary sheet that references the data sheet
 summary_sheet = document.add_sheet!('Summary')
 summary_sheet.add_column!(:description)
@@ -146,8 +142,12 @@ summary_sheet.add_row!(:sales_summary)
   .add!(:description, value: 'Total Sales')
   .add!(:amount, data_sheet.cell_ref(:value, :row_1))
 
-summary_sheet.position_rows!
-summary_sheet.generate_sheet!
+# Position and generate all sheets at once (after all content is added)
+# This allows bidirectional references between sheets
+document.sheet_by_name.values.each do |sheet|
+  sheet.position_rows!
+  sheet.generate_sheet!
+end
 ```
 
 ### Styling

examples/basic_spreadsheet.rb

@@ -4,7 +4,6 @@
 
 # Basic example of creating a simple spreadsheet with Zaxcel
 
-require 'bundler/setup'
 require 'zaxcel'
 
 # Create a new document
@@ -86,7 +85,7 @@
   style: :total,
 )
 
-# Position rows before generating so references resolve
+# Position and generate sheet (do this after all rows/columns are defined)
 sheet.position_rows!
 sheet.generate_sheet!
 

examples/cross_sheet_references.rb

@@ -3,8 +3,6 @@
 # frozen_string_literal: true
 
 # Example demonstrating cross-sheet references in Zaxcel
-
-require 'bundler/setup'
 require 'zaxcel'
 
 document = Zaxcel::Document.new
@@ -36,9 +34,6 @@
   product_rows << row
 end
 
-data_sheet.position_rows!
-data_sheet.generate_sheet!
-
 # Create a summary sheet that references the data sheet
 summary_sheet = document.add_sheet!('Summary')
 summary_sheet.add_column!(:metric, header: 'Metric', header_style: :header)
@@ -92,8 +87,13 @@
   .add!(:metric, value: 'Highest Price')
   .add!(:value, value: max_price, style: :currency)
 
-summary_sheet.position_rows!
-summary_sheet.generate_sheet!
+# Position and generate all sheets at once (after all sheets are built)
+document.sheet_by_name.values.each do |sheet|
+  sheet.position_rows!
+end
+document.sheet_by_name.values.each do |sheet|
+  sheet.generate_sheet!
+end
 
 # Write to file (binary-safe via Tempfile)
 filename = 'cross_sheet_example.xlsx'