Improved layout stability for dynamic components that use the TotalPages property to generate content

Source/QuestPDF.LayoutTests/TestEngine/LayoutTestExecutor.cs

@@ -22,7 +22,7 @@ internal static class LayoutTestExecutor
         {
             // inject dependencies
             var pageContext = new PageContext();
-            pageContext.ResetPageNumber();
+            pageContext.ProceedToNextRenderingPhase();
 
             var canvas = new PreviewerCanvas();
         

Source/QuestPDF/Drawing/DocumentGenerator.cs

@@ -119,7 +119,7 @@ namespace QuestPDF.Drawing
 
             var pageContext = new PageContext();
             RenderPass(pageContext, new FreeCanvas(), content);
-            pageContext.ResetPageNumber();
+            pageContext.ProceedToNextRenderingPhase();
             RenderPass(pageContext, canvas, content);
         }
         
@@ -147,7 +147,7 @@ namespace QuestPDF.Drawing
                     RenderPass(documentPageContext, new FreeCanvas(), documentPart.Content);
                 }
                 
-                documentPageContext.ResetPageNumber();
+                documentPageContext.ProceedToNextRenderingPhase();
 
                 foreach (var documentPart in documentParts)
                 {
@@ -163,7 +163,7 @@ namespace QuestPDF.Drawing
                     pageContext.SetDocumentId(documentPart.DocumentId);
                     
                     RenderPass(pageContext, new FreeCanvas(), documentPart.Content);
-                    pageContext.ResetPageNumber();
+                    pageContext.ProceedToNextRenderingPhase();
                     RenderPass(pageContext, canvas, documentPart.Content);
                 }
             }

Source/QuestPDF/Elements/Dynamic.cs

@@ -67,7 +67,7 @@ namespace QuestPDF.Elements
                 UseOriginalImage = UseOriginalImage,
                 
                 PageNumber = PageContext.CurrentPage,
-                TotalPages = PageContext.DocumentLength,
+                TotalPages = PageContext.IsInitialRenderingPhase ? int.MaxValue : PageContext.DocumentLength,
                 AvailableSize = availableSize
             };
             
@@ -104,8 +104,11 @@ namespace QuestPDF.Elements
         /// Returns the total count of pages in the document.
         /// </summary>
         /// <remarks>
-        /// Document rendering occurs in two phases.
-        /// The value of this property might be imprecise during the initial rendering phase.
+        /// <para>
+        /// Document rendering process is performed in two phases.
+        /// During the first phase, the value of this property is equal to <c>int.MaxValue</c> to indicate its unavailability.
+        /// </para>
+        /// <para>Please note that using this property may result with unstable layouts and unpredicted behaviors, especially when generating conditional content of various sizes.</para>
         /// </remarks>
         public int TotalPages { get; internal set; }
         

Source/QuestPDF/Infrastructure/IPageContext.cs

@@ -11,6 +11,7 @@
     
     internal interface IPageContext
     {
+        bool IsInitialRenderingPhase { get; }
         int DocumentLength { get; }
         int CurrentPage { get; }
         void SetSectionPage(string name);

Source/QuestPDF/Infrastructure/PageContext.cs

@@ -5,6 +5,7 @@ namespace QuestPDF.Infrastructure
 {
     internal sealed class PageContext : IPageContext
     {
+        public bool IsInitialRenderingPhase { get; private set; } = true;
         public int DocumentLength { get; private set; }
         private List<DocumentLocation> Locations { get; } = new();
         
@@ -16,8 +17,9 @@ namespace QuestPDF.Infrastructure
             CurrentDocumentId = id;
         }
         
-        internal void ResetPageNumber()
+        internal void ProceedToNextRenderingPhase()
         {
+            IsInitialRenderingPhase = false;
             CurrentPage = 0;
         }