Imaplement inject json data (#5)

* replace image of sample code in landing page

* feat(*): support async events and inject json data in core

* chore(*): bump versions to 0.0.7

Author: PejmanNik

examples/zeroReport/index.html

@@ -23,6 +23,7 @@ <h1>End of Section</h1>
             <h4>Page <span data-pz-v-page-number></span> of <span data-pz-v-total-pages></span> Footer </h4>
         </div>
         <div data-pz-page-content>
+            <p>Hello <span data-pz-v-json-data-key="info.name"></span>!</p>
             <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the
                 industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and
                 scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap

examples/zeroReport/ssg.ts

@@ -20,7 +20,14 @@ try {
 
     const pdf = await reportToPdf(
         page,
-        new URL(`file://${import.meta.dirname}/index.html`)
+        new URL(`file://${import.meta.dirname}/index.html`),
+        {
+            info: {
+                name: 'Mike',
+                lastName: 'Ross',
+                age: 24,
+            },
+        }
     );
 
     await fs.writeFile('index.pdf', pdf);

packages/core/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@paprize/core",
-    "version": "0.0.6",
+    "version": "0.0.7",
     "description": "Paginate DOM elements for professional, print-ready reports",
     "type": "module",
     "files": [

packages/core/src/report/EventDispatcher.test.ts

@@ -12,32 +12,38 @@ describe('EventDispatcher', () => {
         dispatcher = new EventDispatcher<TestEvents>();
     });
 
-    it('should add and call event listeners', () => {
+    it('should add and call event listeners', async () => {
         const handler = vi.fn();
         dispatcher.addEventListener('foo', handler);
-        dispatcher.dispatch('foo', 1, 'x');
+
+        await dispatcher.dispatch('foo', 1, 'x');
+
         expect(handler).toHaveBeenCalledWith(1, 'x');
     });
 
-    it('should remove event listeners', () => {
+    it('should remove event listeners', async () => {
         const handler = vi.fn();
         const remove = dispatcher.addEventListener('foo', handler);
         remove();
-        dispatcher.dispatch('foo', 2, 'y');
+
+        await dispatcher.dispatch('foo', 2, 'y');
+
         expect(handler).not.toHaveBeenCalled();
     });
 
-    it('should support multiple listeners for the same event', () => {
+    it('should support multiple listeners for the same event', async () => {
         const handler1 = vi.fn();
         const handler2 = vi.fn();
         dispatcher.addEventListener('foo', handler1);
         dispatcher.addEventListener('foo', handler2);
-        dispatcher.dispatch('foo', 3, 'z');
+
+        await dispatcher.dispatch('foo', 3, 'z');
+
         expect(handler1).toHaveBeenCalledWith(3, 'z');
         expect(handler2).toHaveBeenCalledWith(3, 'z');
     });
 
-    it('should do nothing if dispatching an event with no listeners', () => {
-        expect(() => dispatcher.dispatch('bar')).not.toThrow();
+    it('should do nothing if dispatching an event with no listeners', async () => {
+        await expect(dispatcher.dispatch('bar')).resolves.toBe(undefined);
     });
 });

packages/core/src/report/EventDispatcher.ts

@@ -7,7 +7,7 @@ type EventHandler<TKey extends keyof TEvents, TEvents> = TEvents[TKey] extends (
 export class EventDispatcher<TEvents> {
     private registry = new Map<
         keyof TEvents,
-        Set<(...args: unknown[]) => void>
+        Set<(...args: unknown[]) => unknown | Promise<unknown>>
     >();
 
     public addEventListener<T extends keyof TEvents>(
@@ -34,7 +34,7 @@ export class EventDispatcher<TEvents> {
         registry.set(name, listeners);
     }
 
-    public dispatch<T extends keyof TEvents>(
+    public async dispatch<T extends keyof TEvents>(
         name: T,
         ...args: Parameters<EventHandler<T, TEvents>>
     ) {
@@ -46,7 +46,7 @@ export class EventDispatcher<TEvents> {
         }
 
         for (const listener of listeners) {
-            listener(...args);
+            await listener(...args);
         }
     }
 }

packages/core/src/report/ReportBuilder.test.ts

@@ -4,6 +4,7 @@ import { Paginator } from '../paginate/Paginator';
 import { paprize_isInitialized, paprize_isReady } from '../window';
 import type { SectionComponents } from './sectionComponents';
 import { globalStyleId } from '../constants';
+import { jsonDataReader } from './utils';
 
 vi.mock('../paginate/Paginator', () => {
     const paginate = vi.fn();
@@ -22,6 +23,7 @@ vi.mock('./utils', async () => {
             sectionFooterHeight: 5,
         }),
         createSectionPageHeightPlugin: vi.fn().mockReturnValue({}),
+        jsonDataReader: vi.fn(),
     };
 });
 
@@ -53,7 +55,7 @@ describe('ReportBuilder', () => {
 
     it.for([true, false])(
         'tryAddSection should add a section and dispatch sectionCreated',
-        (withsuspense) => {
+        async (withsuspense) => {
             const sectionCreated = vi.fn();
             rb.monitor.addEventListener('sectionCreated', sectionCreated);
 
@@ -62,7 +64,11 @@ describe('ReportBuilder', () => {
                 suspense: withsuspense ? [Promise.resolve()] : [],
             };
 
-            const added = rb.tryAddSection(testOptions, components, () => {});
+            const added = await rb.tryAddSection(
+                testOptions,
+                components,
+                () => {}
+            );
             expect(added).toBe(true);
 
             expect(sectionCreated).toHaveBeenCalled();
@@ -74,9 +80,9 @@ describe('ReportBuilder', () => {
         }
     );
 
-    it('tryAddSection should return false if section id already exists', () => {
-        rb.tryAddSection(options, components, () => {});
-        const result = rb.tryAddSection(options, components, () => {});
+    it('tryAddSection should return false if section id already exists', async () => {
+        await rb.tryAddSection(options, components, () => {});
+        const result = await rb.tryAddSection(options, components, () => {});
         expect(result).toBe(false);
     });
 
@@ -115,7 +121,7 @@ describe('ReportBuilder', () => {
 
         const onPaginationCompleted = vi.fn();
 
-        const added = rb.tryAddSection(
+        const added = await rb.tryAddSection(
             options,
             testComponents,
             onPaginationCompleted
@@ -160,7 +166,7 @@ describe('ReportBuilder', () => {
         const section1 = 'se1';
         const section2 = 'se2';
 
-        rb.tryAddSection(
+        await rb.tryAddSection(
             {
                 ...options,
                 id: section1,
@@ -169,7 +175,7 @@ describe('ReportBuilder', () => {
             components,
             onPaginationCompleted
         );
-        const added = rb.tryAddSection(
+        const added = await rb.tryAddSection(
             {
                 ...options,
                 id: section2,
@@ -209,7 +215,7 @@ describe('ReportBuilder', () => {
         const paginateMock = vi.mocked(Paginator.paginate);
         paginateMock.mockReturnValue(['<div>page1</div>']);
 
-        rb.tryAddSection(options, components, vi.fn());
+        await rb.tryAddSection(options, components, vi.fn());
 
         const section1Promise = rb.schedulePagination();
         await new Promise((resolve) => setTimeout(resolve, 0));
@@ -228,7 +234,7 @@ describe('ReportBuilder', () => {
         const paginateMock = vi.mocked(Paginator.paginate);
         paginateMock.mockReturnValue(['<div>page1</div>']);
 
-        rb.tryAddSection(options, components, vi.fn());
+        await rb.tryAddSection(options, components, vi.fn());
 
         const section1Promise = rb.schedulePagination();
         const section2Promise = rb.schedulePagination();
@@ -246,7 +252,7 @@ describe('ReportBuilder', () => {
         const sectionId = 'test-section';
         const onPaginationCompleted = vi.fn();
 
-        rb.tryAddSection(
+        await rb.tryAddSection(
             {
                 id: sectionId,
                 size: { width: '100px', height: '200px' },
@@ -260,6 +266,39 @@ describe('ReportBuilder', () => {
 
         expect(result.sections.length).toBe(0);
     });
+
+    it('getJsonData should call jsonDataReader once', async () => {
+        const data = {
+            a: 'a',
+        };
+        vi.mocked(jsonDataReader).mockResolvedValue(data);
+
+        const result1 = await rb.getJsonData({ a: 'b' });
+        const result2 = await rb.getJsonData({ a: 'b' });
+
+        expect(result1).toMatchObject(data);
+        expect(result2).toMatchObject(data);
+        expect(vi.mocked(jsonDataReader)).toHaveBeenCalledOnce();
+    });
+
+    it('getJsonData should return default value when jsonDataReader is not available', async () => {
+        const defaultData = {
+            a: 'a',
+        };
+        vi.mocked(jsonDataReader).mockResolvedValue(undefined);
+
+        const result = await rb.getJsonData(defaultData);
+
+        expect(result).toMatchObject(defaultData);
+    });
+
+    it('getJsonData should return null without default value and jsonDataReader', async () => {
+        vi.mocked(jsonDataReader).mockResolvedValue(null);
+
+        const result = await rb.getJsonData();
+
+        expect(result).toBeNull();
+    });
 });
 
 describe('ReportBuilder constructor', () => {

packages/core/src/report/ReportBuilder.ts

@@ -12,7 +12,12 @@ import type {
 } from './ReportBuilderEvents';
 import { reportStyles } from './reportStyles';
 import { cloneComponents, type SectionComponents } from './sectionComponents';
-import { calculatePageSizes, createSectionPageHeightPlugin } from './utils';
+import {
+    calculatePageSizes,
+    createSectionPageHeightPlugin,
+    jsonDataReader,
+    lazyPromise,
+} from './utils';
 import { paprize_isInitialized, paprize_isReady } from '../window';
 import { globalStyleId } from '../constants';
 import { PromiseTracker } from './PromiseTracker';
@@ -123,11 +128,11 @@ export class ReportBuilder {
      * @param onPaginationCompleted - Callback invoked when pagination for the section is completed.
      * @returns `true` if the section was added to the report’s section list, or `false` if it already exists.
      */
-    public tryAddSection(
+    public async tryAddSection(
         options: SectionOptions,
         components: SectionComponents,
         onPaginationCompleted: (pages: PageContext[]) => void
-    ): boolean {
+    ): Promise<boolean> {
         if (this._sections.has(options.id)) {
             return false;
         }
@@ -155,7 +160,8 @@ export class ReportBuilder {
         this._injectStyle(
             reportStyles.sectionPageMedia(options.id, options.size)
         );
-        this._monitor.dispatch('sectionCreated', context);
+
+        await this._monitor.dispatch('sectionCreated', context);
 
         return true;
     }
@@ -204,6 +210,27 @@ export class ReportBuilder {
         return this._executePagination();
     }
 
+    /**
+     * Retrieves JSON data injected by **@paprize/puppeteer** during server-side rendering (SSR).
+     *
+     * If no injected data is available, the function returns the provided `defaultData`, or `null` if none is given.
+     *
+     * ⚠️ **Important Notes:**
+     * - This function is **not type-safe** — it performs **no runtime type validation** on the returned data.
+     * - It is available **only during server-side rendering** when using **@paprize/puppeteer**.
+     * - When used in **client-side rendering** or **development** mode, you should provide a `defaultData` value for testing purposes.
+     *
+     * @template T - The expected type of the injected JSON data.
+     * @param defaultData - Optional fallback value to return if no injected data is found.
+     * @returns A promise resolving to the injected JSON data if available, otherwise the provided default value or `null`.
+     */
+    public async getJsonData<T>(defaultData?: T): Promise<T | null> {
+        const json = await this._lazyJsonDataReader().catch(() => defaultData);
+        return (json as T) ?? defaultData ?? null;
+    }
+
+    private _lazyJsonDataReader = lazyPromise(jsonDataReader);
+
     private async _executePagination(): Promise<ScheduleResult> {
         this._paginationInProgress = true;
         this._currentAbortController = new AbortController();
@@ -249,9 +276,9 @@ export class ReportBuilder {
             }
 
             const reportTracker = new PromiseTracker();
-            reportTracker.monitor.addEventListener('onChange', () => {
+            reportTracker.monitor.addEventListener('onChange', async () => {
                 logger.debug(logPrefix, 'Report pagination completed.');
-                this._monitor.dispatch('paginationCycleCompleted', {
+                await this._monitor.dispatch('paginationCycleCompleted', {
                     sections: [...this._sections.values()].map(
                         (s) => s.context
                     ),
@@ -395,7 +422,7 @@ export class ReportBuilder {
         state.onPaginationCompleted(pageContexts);
 
         for (const pageContext of pageContexts) {
-            this._monitor.dispatch('pageCompleted', pageContext);
+            await this._monitor.dispatch('pageCompleted', pageContext);
         }
 
         const sectionContext: SectionContext = {
@@ -409,6 +436,6 @@ export class ReportBuilder {
             context: sectionContext,
         });
 
-        this._monitor.dispatch('sectionCompleted', sectionContext);
+        await this._monitor.dispatch('sectionCompleted', sectionContext);
     }
 }