@softwear/latestcollectioncore 1.0.176 → 1.0.178

package/dist/pdf.d.ts

@@ -54,6 +54,8 @@ export interface ContainerLayoutObject extends BaseLayoutObject {
     minHeightBeforeBreak?: number;
     /** When true, container and children are drawn only once at the end of the report, not on every page */
     printOnlyAtEnd?: boolean;
+    /** Only effective on top-level `layout.objects` (PDF engine ignores this flag on nested containers). */
+    printOnlyAtStart?: boolean;
 }
 export type LayoutObject = TextLayoutObject | FieldLayoutObject | RectangleLayoutObject | ImageLayoutObject | ContainerLayoutObject;
 export interface Layout {

package/dist/reports.js

@@ -43,6 +43,12 @@ function getProperty(propertyName, object) {
     }
     return property;
 }
+/** Repeat once over the current buffer when the container is only a visual group (no `source` binding). */
+function containerLoopSource(container, printBuffer) {
+    if (!container.source || container.source === '')
+        return [printBuffer];
+    return getProperty(container.source, printBuffer);
+}
 /** jsPDF font style strings. fontStyle bitmask: 0=normal, 1=bold, 2=italic, 3=bold+italic */
 const FONT_STYLES = ['normal', 'bold', 'italic', 'bolditalic'];
 /** Recursively collect used custom fonts from layout objects (text/field with fontFamily) and layout default. */
@@ -160,7 +166,7 @@ function collectImageUrlsFromLayout(layout, printBuffer) {
             }
             if (object.type !== 'container')
                 return;
-            const source = object.printOnlyAtEnd === true && (!object.source || object.source === '') ? [currentPrintBuffer] : getProperty(object.source, currentPrintBuffer);
+            const source = containerLoopSource(object, currentPrintBuffer);
             if (!Array.isArray(source))
                 return;
             source.forEach((containerPrintBuffer) => walk(object.children, containerPrintBuffer));
@@ -450,8 +456,7 @@ addObjectToPDF = function (originX, originY, doc, object, printBuffer, paperSize
     // Recursively draw all child objects from a container object
     if (object.type == 'container') {
         let originX = x * 10, originY = y * 10;
-        const isPrintOnlyAtEnd = object.printOnlyAtEnd === true;
-        const source = isPrintOnlyAtEnd && (!object.source || object.source === '') ? [printBuffer] : getProperty(object.source, printBuffer);
+        const source = containerLoopSource(object, printBuffer);
         if (source === undefined) {
             (_a = options.onAlert) === null || _a === void 0 ? void 0 : _a.call(options, { header: 'containernotfound', body: object.source, type: 'warning', timeout: 10000 });
             return absoluteLowerRightHandSide;
@@ -657,16 +662,27 @@ function genPDF(layout, printBuffer, options = {}) {
             yield embedFontsInDoc(measurementDoc, usedFonts, options);
         }
         drawStaticPartOfPage(measurementDoc, layout, printBuffer, paperSize, options, measurementContext);
-        // Draw containers in measurement mode (same order as render: normal first, then printOnlyAtEnd on fresh page)
+        // Draw containers in measurement mode (same order as render)
+        let measurementTopPrintedStartBottomTenths = 0;
+        layout.objects
+            .filter((object) => object.type == 'container' && object.printOnlyAtStart)
+            .forEach((object) => {
+            const lh = addObjectToPDF(0, 0, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext);
+            measurementTopPrintedStartBottomTenths = Math.max(measurementTopPrintedStartBottomTenths, lh.y * 10);
+        });
         layout.objects
-            .filter((object) => object.type == 'container' && !object.printOnlyAtEnd)
+            .filter((object) => object.type == 'container' &&
+            !object.printOnlyAtEnd &&
+            !object.printOnlyAtStart)
             .forEach((object) => {
-            addObjectToPDF(0, 0, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext);
+            const bump = Math.max(0, measurementTopPrintedStartBottomTenths - object.y);
+            addObjectToPDF(0, bump, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext);
         });
         layout.objects
             .filter((object) => object.type == 'container' && object.printOnlyAtEnd)
             .forEach((object) => {
-            addObjectToPDF(0, 0, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext);
+            const bump = Math.max(0, measurementTopPrintedStartBottomTenths - object.y);
+            addObjectToPDF(0, bump, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext);
         });
         // Get total page count from measurement pass
         const totalPageCount = measurementContext.currentPageCount || 1;
@@ -685,16 +701,27 @@ function genPDF(layout, printBuffer, options = {}) {
             defaultFontFamily: layout.defaultFontFamily,
         };
         drawStaticPartOfPage(doc, layout, printBuffer, paperSize, options, renderContext);
-        // Draw containers in rendering mode (normal containers first)
+        let renderTopPrintedStartBottomTenths = 0;
+        layout.objects
+            .filter((object) => object.type == 'container' && object.printOnlyAtStart)
+            .forEach((object) => {
+            const lh = addObjectToPDF(0, 0, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext);
+            renderTopPrintedStartBottomTenths = Math.max(renderTopPrintedStartBottomTenths, lh.y * 10);
+        });
+        // Draw containers in rendering mode (body containers after printOnlyAtStart)
         layout.objects
-            .filter((object) => object.type == 'container' && !object.printOnlyAtEnd)
+            .filter((object) => object.type == 'container' &&
+            !object.printOnlyAtEnd &&
+            !object.printOnlyAtStart)
             .forEach((object) => {
-            addObjectToPDF(0, 0, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext);
+            const bump = Math.max(0, renderTopPrintedStartBottomTenths - object.y);
+            addObjectToPDF(0, bump, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext);
         });
         // Draw printOnlyAtEnd containers once at the end (at their layout coordinates on current page)
         const printOnlyAtEndContainers = layout.objects.filter((object) => object.type == 'container' && object.printOnlyAtEnd);
         printOnlyAtEndContainers.forEach((object) => {
-            addObjectToPDF(0, 0, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext);
+            const bump = Math.max(0, renderTopPrintedStartBottomTenths - object.y);
+            addObjectToPDF(0, bump, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext);
         });
         return doc;
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softwear/latestcollectioncore",
-  "version": "1.0.176",
+  "version": "1.0.178",
   "description": "Core functions for LatestCollections applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/pdf.ts

@@ -61,6 +61,8 @@ export interface ContainerLayoutObject extends BaseLayoutObject {
   minHeightBeforeBreak?: number
   /** When true, container and children are drawn only once at the end of the report, not on every page */
   printOnlyAtEnd?: boolean
+  /** Only effective on top-level `layout.objects` (PDF engine ignores this flag on nested containers). */
+  printOnlyAtStart?: boolean
 }
 
 export type LayoutObject = TextLayoutObject | FieldLayoutObject | RectangleLayoutObject | ImageLayoutObject | ContainerLayoutObject

package/src/reports.ts

@@ -92,6 +92,12 @@ function getProperty(propertyName: string, object: any): any {
   return property
 }
 
+/** Repeat once over the current buffer when the container is only a visual group (no `source` binding). */
+function containerLoopSource(container: ContainerLayoutObject, printBuffer: any): any {
+  if (!container.source || container.source === '') return [printBuffer]
+  return getProperty(container.source, printBuffer)
+}
+
 /** jsPDF font style strings. fontStyle bitmask: 0=normal, 1=bold, 2=italic, 3=bold+italic */
 const FONT_STYLES = ['normal', 'bold', 'italic', 'bolditalic'] as const
 
@@ -222,7 +228,7 @@ function collectImageUrlsFromLayout(layout: Layout, printBuffer: any): string[]
 
       if (object.type !== 'container') return
 
-      const source = (object as any).printOnlyAtEnd === true && (!object.source || object.source === '') ? [currentPrintBuffer] : getProperty(object.source, currentPrintBuffer)
+      const source = containerLoopSource(object as ContainerLayoutObject, currentPrintBuffer)
       if (!Array.isArray(source)) return
       source.forEach((containerPrintBuffer) => walk(object.children, containerPrintBuffer))
     })
@@ -539,8 +545,7 @@ addObjectToPDF = function (
     let originX = x * 10,
       originY = y * 10
 
-    const isPrintOnlyAtEnd = (object as any).printOnlyAtEnd === true
-    const source = isPrintOnlyAtEnd && (!object.source || object.source === '') ? [printBuffer] : getProperty(object.source, printBuffer)
+    const source = containerLoopSource(object as ContainerLayoutObject, printBuffer)
     if (source === undefined) {
       options.onAlert?.({ header: 'containernotfound', body: object.source, type: 'warning', timeout: 10000 })
       return absoluteLowerRightHandSide
@@ -780,16 +785,30 @@ export async function genPDF(layout: Layout, printBuffer: any, options: GenPdfOp
   }
   drawStaticPartOfPage(measurementDoc, layout, printBuffer, paperSize, options, measurementContext)
 
-  // Draw containers in measurement mode (same order as render: normal first, then printOnlyAtEnd on fresh page)
+  // Draw containers in measurement mode (same order as render)
+  let measurementTopPrintedStartBottomTenths = 0
+  layout.objects
+    .filter((object) => object.type == 'container' && (object as ContainerLayoutObject).printOnlyAtStart)
+    .forEach((object) => {
+      const lh = addObjectToPDF(0, 0, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext)
+      measurementTopPrintedStartBottomTenths = Math.max(measurementTopPrintedStartBottomTenths, lh.y * 10)
+    })
   layout.objects
-    .filter((object) => object.type == 'container' && !(object as any).printOnlyAtEnd)
+    .filter(
+      (object) =>
+        object.type == 'container' &&
+        !(object as ContainerLayoutObject).printOnlyAtEnd &&
+        !(object as ContainerLayoutObject).printOnlyAtStart
+    )
     .forEach((object) => {
-      addObjectToPDF(0, 0, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext)
+      const bump = Math.max(0, measurementTopPrintedStartBottomTenths - object.y)
+      addObjectToPDF(0, bump, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext)
     })
   layout.objects
-    .filter((object) => object.type == 'container' && (object as any).printOnlyAtEnd)
+    .filter((object) => object.type == 'container' && (object as ContainerLayoutObject).printOnlyAtEnd)
     .forEach((object) => {
-      addObjectToPDF(0, 0, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext)
+      const bump = Math.max(0, measurementTopPrintedStartBottomTenths - object.y)
+      addObjectToPDF(0, bump, measurementDoc, object, printBuffer, paperSize, layout, options, printBuffer, [], measurementContext)
     })
 
   // Get total page count from measurement pass
@@ -811,17 +830,34 @@ export async function genPDF(layout: Layout, printBuffer: any, options: GenPdfOp
   }
   drawStaticPartOfPage(doc, layout, printBuffer, paperSize, options, renderContext)
 
-  // Draw containers in rendering mode (normal containers first)
+  let renderTopPrintedStartBottomTenths = 0
   layout.objects
-    .filter((object) => object.type == 'container' && !(object as any).printOnlyAtEnd)
+    .filter((object) => object.type == 'container' && (object as ContainerLayoutObject).printOnlyAtStart)
     .forEach((object) => {
-      addObjectToPDF(0, 0, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext)
+      const lh = addObjectToPDF(0, 0, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext)
+      renderTopPrintedStartBottomTenths = Math.max(renderTopPrintedStartBottomTenths, lh.y * 10)
+    })
+
+  // Draw containers in rendering mode (body containers after printOnlyAtStart)
+  layout.objects
+    .filter(
+      (object) =>
+        object.type == 'container' &&
+        !(object as ContainerLayoutObject).printOnlyAtEnd &&
+        !(object as ContainerLayoutObject).printOnlyAtStart
+    )
+    .forEach((object) => {
+      const bump = Math.max(0, renderTopPrintedStartBottomTenths - object.y)
+      addObjectToPDF(0, bump, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext)
     })
 
   // Draw printOnlyAtEnd containers once at the end (at their layout coordinates on current page)
-  const printOnlyAtEndContainers = layout.objects.filter((object) => object.type == 'container' && (object as any).printOnlyAtEnd)
+  const printOnlyAtEndContainers = layout.objects.filter(
+    (object) => object.type == 'container' && (object as ContainerLayoutObject).printOnlyAtEnd
+  )
   printOnlyAtEndContainers.forEach((object) => {
-    addObjectToPDF(0, 0, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext)
+    const bump = Math.max(0, renderTopPrintedStartBottomTenths - object.y)
+    addObjectToPDF(0, bump, doc, object, printBuffer, paperSize, layout, options, printBuffer, [], renderContext)
   })
   return doc
 }

package/test/reports.spec.ts

@@ -1,8 +1,15 @@
 import { describe, expect, it } from 'vitest'
 import { genPDF } from '../src/reports'
 import type { Layout } from '../src/pdf'
-// import fs from 'fs'
 
+/** Tiny valid JPEG as data URL — avoids flaky network-dependent image fetch in CI/sandbox. */
+function offlineJpegFixture(): string {
+  const b64 =
+    '/9j/4AAQSkZJRgABAQIAASABIAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAAKAAoDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAb/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIQAxAAAAHhAP/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAQkCf//EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQMBAT8B/8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAgMBPwF//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQYPAj//xAAVEAEAAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQBPCQ//Z'
+  return `data:image/jpeg;base64,${b64}`
+}
+
+// URL still used so collectImageUrlsFromLayout resolves the layout object
 const imageUrl = 'https://upload.wikimedia.org/wikipedia/commons/thumb/7/79/Phillips_PM5538.jpg/500px-Phillips_PM5538.jpg'
 
 describe('genPDF', () => {
@@ -59,7 +66,14 @@ describe('genPDF', () => {
       title: 'Minimal PDF',
     }
 
-    const doc = await genPDF(layout, printBuffer)
+    const doc = await genPDF(layout, printBuffer, {
+      loadImage: async () => ({
+        dataUrl: offlineJpegFixture(),
+        format: 'JPEG',
+        width: 500,
+        height: 375,
+      }),
+    })
     const pdf = doc.output('arraybuffer')
     const pdfText = Buffer.from(pdf).toString('latin1')
 
@@ -71,4 +85,128 @@ describe('genPDF', () => {
     expect(pdfText).toContain(printBuffer.title)
     // fs.writeFileSync('test.pdf', Buffer.from(pdf))
   })
+
+  it('draws printOnlyAtStart before body containers and printOnlyAtEnd after', async () => {
+    const textChild = (name: string, y: number, label: string) =>
+      ({
+        type: 'text' as const,
+        name,
+        x: 20,
+        y,
+        width: 400,
+        height: 40,
+        active: true,
+        text: label,
+        textAlign: 1 as const,
+        fontFamily: 'Helvetica',
+        fontSize: 24,
+        fontStyle: 0,
+      }) as const
+
+    const layout: Layout = {
+      name: 'order-test',
+      paperSize: { width: 210, height: 297, footerHeight: 20 },
+      objects: [
+        {
+          type: 'container',
+          x: 0,
+          y: 40,
+          width: 500,
+          height: 80,
+          active: true,
+          source: '',
+          printOnlyAtStart: true,
+          children: [textChild('start', 0, 'START_ONLY')],
+        },
+        {
+          type: 'container',
+          x: 0,
+          y: 120,
+          width: 500,
+          height: 80,
+          active: true,
+          source: '',
+          children: [textChild('mid', 0, 'BODY_MIDDLE')],
+        },
+        {
+          type: 'container',
+          x: 0,
+          y: 200,
+          width: 500,
+          height: 80,
+          active: true,
+          source: '',
+          printOnlyAtEnd: true,
+          children: [textChild('end', 0, 'END_ONLY')],
+        },
+      ],
+    }
+    const doc = await genPDF(layout, {})
+    const pdfText = Buffer.from(doc.output('arraybuffer')).toString('latin1')
+    const iStart = pdfText.indexOf('(START_ONLY)')
+    const iMid = pdfText.indexOf('(BODY_MIDDLE)')
+    const iEnd = pdfText.indexOf('(END_ONLY)')
+    expect(iStart).toBeGreaterThanOrEqual(0)
+    expect(iMid).toBeGreaterThanOrEqual(0)
+    expect(iEnd).toBeGreaterThanOrEqual(0)
+    expect(iStart).toBeLessThan(iMid)
+    expect(iMid).toBeLessThan(iEnd)
+  })
+
+  it('stacks top-level body containers below printOnlyAtStart when they share the same layout y', async () => {
+    const text = (name: string, label: string, y = 0, fontSize = 80) =>
+      ({
+        type: 'text' as const,
+        name,
+        x: 20,
+        y,
+        width: 900,
+        height: 400,
+        active: true,
+        text: label,
+        textAlign: 1 as const,
+        fontFamily: 'Helvetica',
+        fontSize,
+        fontStyle: 0,
+      }) as const
+
+    const sharedY = 400
+    const layout: Layout = {
+      name: 'same-y-stack',
+      paperSize: { width: 210, height: 297, footerHeight: 20 },
+      objects: [
+        {
+          type: 'container',
+          x: 0,
+          y: sharedY,
+          width: 1000,
+          height: 900,
+          active: true,
+          source: '',
+          printOnlyAtStart: true,
+          children: [text('h', 'PAGE1_HEADER_BLOCK')],
+        },
+        {
+          type: 'container',
+          x: 0,
+          y: sharedY,
+          width: 1000,
+          height: 500,
+          active: true,
+          source: '',
+          children: [text('b', 'BODY_AFTER_STACK', 0, 32)],
+        },
+      ],
+    }
+
+    const doc = await genPDF(layout, {})
+    const pdfText = Buffer.from(doc.output('arraybuffer')).toString('latin1')
+    expect(pdfText).toContain('(PAGE1_HEADER_BLOCK)')
+    expect(pdfText).toContain('(BODY_AFTER_STACK)')
+    const iH = pdfText.indexOf('(PAGE1_HEADER_BLOCK)')
+    const iB = pdfText.indexOf('(BODY_AFTER_STACK)')
+    expect(iH).toBeGreaterThanOrEqual(0)
+    expect(iB).toBeGreaterThanOrEqual(0)
+    expect(iH).toBeLessThan(iB)
+  })
 })