@pdfme/common 4.5.2 → 5.0.0-dev.1

package/README.md

@@ -27,6 +27,7 @@
 
 <p align="center">TypeScript base PDF generator and React base UI. Open source, developed by the community, and completely free to use under the MIT license!</p>
 
+
 ## Features
 
 | Fast PDF Generator                                                                           | Easy PDF template design                              | Simple JSON template                                           |
@@ -70,6 +71,9 @@ npm i @pdfme/ui @pdfme/common
 
 \*You must install `@pdfme/common` regardless of which package you use.
 
+On NPM stable releases are published to the `latest` tag, and pre-releases are published to the `next` tag.
+On the `dev` tag you can find releases for every commit to the `main` branch.
+
 The following type, function and classes are available in pdfme.
 
 `@pdfme/common`
@@ -117,9 +121,8 @@ The following image is a good illustration of a template.
 **basePdf** can be given a `string`(base64), `ArrayBuffer`, or `Uint8Array`.  
 A blank A4 PDF can be imported with `BLANK_PDF`. You can use it to check how it works.
 
-**schemas** can only utilize text by default, but you can load images and various barcodes like QR codes as plugins from the `@pdfme/schemas` package.  
-Additionally, you can create your own schemas, allowing you to render types other than the ones mentioned above.  
-Check detail about [Custom Schemas](https://pdfme.com/docs/custom-schemas) from here
+**Schemas** can only utilize text by default, but you can load images and various barcodes like QR codes as plugins from the `@pdfme/schemas` package.  
+Additionally, you can create your own schemas, allowing you to render types other than the ones mentioned above. Check detail about [Custom Schemas](https://pdfme.com/docs/custom-schemas) from here.
 
 Let's take a look at some specific data.  
 (If you are using TypeScript, you can import the Template type.)
@@ -132,26 +135,29 @@ import { Template, BLANK_PDF } from '@pdfme/common';
 const template: Template = {
   basePdf: BLANK_PDF,
   schemas: [
-    {
-      a: {
+    [
+      {
+        name: 'a',
         type: 'text',
         position: { x: 0, y: 0 },
         width: 10,
         height: 10,
       },
-      b: {
+      {
+        name: 'a',
         type: 'text',
         position: { x: 10, y: 10 },
         width: 10,
         height: 10,
       },
-      c: {
+      {
+        name: 'c',
         type: 'text',
         position: { x: 20, y: 20 },
         width: 10,
         height: 10,
       },
-    },
+    ],
   ],
 };
 ```
@@ -193,7 +199,7 @@ Also, each element in the inputs array corresponds to a page in the PDF, you can
 
 ## UI
 
-The UI is composed of the Designer, Form, and Viewer classes.
+The UI is composed of the [Designer](https://pdfme.com/docs/getting-started#designer), [Form](https://pdfme.com/docs/getting-started#form), and [Viewer](https://pdfme.com/docs/getting-started#viewer) classes.
 
 ### Designer
 
@@ -225,7 +231,6 @@ The designer instance can be manipulated with the following methods.
 - `saveTemplate`
 - `updateTemplate`
 - `getTemplate`
-- `getPageCursor`
 - `onChangeTemplate`
 - `onSaveTemplate`
 - `destroy`
@@ -286,6 +291,72 @@ const viewer = new Viewer({ domContainer, template, inputs });
 
 ![](https://raw.githubusercontent.com/pdfme/pdfme/main/website/static/img/viewer.png)
 
+### Using additional schemas and custom plugins
+
+The examples so far use only the `text` schema type. There are many others built-in within the `@pdfme/schemas` package, and you can use your own:
+
+Here's an example using additional schemas from built-in and custom plugins:
+
+```ts
+import { Template, BLANK_PDF } from '@pdfme/common';
+import { text, barcodes, image } from '@pdfme/schemas';
+import myPlugin from './custom-plugins';
+
+const template: Template = {
+  basePdf: BLANK_PDF,
+  schemas: [
+    [
+      {
+        name: 'example_text',
+        type: 'text',
+        position: { x: 0, y: 0 },
+        width: 40,
+        height: 10,
+      },
+      {
+        name: 'example_image',
+        type: 'image',
+        position: { x: 200, y: 200 },
+        width: 60,
+        height: 40,
+      },
+      {
+        name: 'example_qr_code',
+        type: 'qrcode',
+        position: { x: 100, y: 100 },
+        width: 50,
+        height: 50,
+      },
+    ],
+  ],
+};
+
+const plugins = {
+  Text: multiVariableText,
+  'QR Code': barcodes.qrcode,
+  Image: image,
+  MyPlugin: myPlugin
+}
+
+const inputs = [{ 
+  example_text: 'a1', 
+  example_image: 'data:image/png;base64,iVBORw0KG....', 
+  example_qr_code: 'https://pdfme.com/' 
+}];
+
+generate({ template, inputs, plugins }).then((pdf) => {
+    console.log(pdf);
+});
+
+```
+
+
+
+## Examples using pdfme
+
+If you are looking for code examples using pdfme to get started, please check out the [pdfme-playground](https://github.com/pdfme/pdfme-playground) repository
+or look at the examples in the `websit/src/pages/` folder of this repository. Settings these up is covered in the [DEVELOPMENT.md](DEVELOPMENT.md) file.
+
 ## Special Thanks
 
 - [pdf-lib](https://pdf-lib.js.org/): Used in PDF generation.
@@ -297,7 +368,7 @@ const viewer = new Viewer({ domContainer, template, inputs });
 - [react-moveable](https://daybrush.com/moveable/), [react-selecto](https://github.com/daybrush/selecto), [@scena/react-guides](https://daybrush.com/guides/): Used in Designer UI.
 - [dnd-kit](https://github.com/clauderic/dnd-kit): Used in Designer UI.
 
-  I definitely could not have created pdfme without these libraries. I am grateful to the developers of these libraries.
+I definitely could not have created pdfme without these libraries. I am grateful to the developers of these libraries.
 
 If you want to contribute to pdfme, please check the [Development Guide](https://pdfme.com/docs/development-guide) page.  
 We look forward to your contribution!

package/dist/cjs/__tests__/helper.test.js

@@ -36,8 +36,9 @@ const getSampleFont = () => ({
 const getTemplate = () => ({
     basePdf: src_1.BLANK_PDF,
     schemas: [
-        {
-            a: {
+        [
+            {
+                name: 'a',
                 content: 'a',
                 type: 'text',
                 fontName: 'SauceHanSansJP',
@@ -45,14 +46,15 @@ const getTemplate = () => ({
                 width: 100,
                 height: 100,
             },
-            b: {
+            {
+                name: 'b',
                 content: 'b',
                 type: 'text',
                 position: { x: 0, y: 0 },
                 width: 100,
                 height: 100,
             },
-        },
+        ],
     ],
 });
 describe('mm2pt test', () => {
@@ -101,22 +103,24 @@ describe('checkFont test', () => {
         const _getTemplate = () => ({
             basePdf: src_1.BLANK_PDF,
             schemas: [
-                {
-                    a: {
+                [
+                    {
+                        name: 'a',
                         content: 'a',
                         type: 'text',
                         position: { x: 0, y: 0 },
                         width: 100,
                         height: 100,
                     },
-                    b: {
+                    {
+                        name: 'b',
                         content: 'b',
                         type: 'text',
                         position: { x: 0, y: 0 },
                         width: 100,
                         height: 100,
                     },
-                },
+                ],
             ],
         });
         try {
@@ -181,8 +185,9 @@ Check this document: https://pdfme.com/docs/custom-fonts#about-font-type`);
         const _getTemplate = () => ({
             basePdf: src_1.BLANK_PDF,
             schemas: [
-                {
-                    a: {
+                [
+                    {
+                        name: 'a',
                         type: 'text',
                         content: 'a',
                         fontName: 'SauceHanSansJP2',
@@ -190,14 +195,15 @@ Check this document: https://pdfme.com/docs/custom-fonts#about-font-type`);
                         width: 100,
                         height: 100,
                     },
-                    b: {
+                    {
+                        name: 'b',
                         type: 'text',
                         content: 'b',
                         position: { x: 0, y: 0 },
                         width: 100,
                         height: 100,
                     },
-                },
+                ],
             ],
         });
         try {
@@ -213,8 +219,9 @@ Check this document: https://pdfme.com/docs/custom-fonts`);
         const _getTemplate = () => ({
             basePdf: src_1.BLANK_PDF,
             schemas: [
-                {
-                    a: {
+                [
+                    {
+                        name: 'a',
                         type: 'text',
                         content: 'a',
                         fontName: 'SauceHanSansJP2',
@@ -222,7 +229,8 @@ Check this document: https://pdfme.com/docs/custom-fonts`);
                         width: 100,
                         height: 100,
                     },
-                    b: {
+                    {
+                        name: 'b',
                         type: 'text',
                         content: 'b',
                         fontName: 'SauceHanSerifJP2',
@@ -230,7 +238,7 @@ Check this document: https://pdfme.com/docs/custom-fonts`);
                         width: 100,
                         height: 100,
                     },
-                },
+                ],
             ],
         });
         try {
@@ -299,8 +307,8 @@ describe('checkPlugins test', () => {
     test('success test: type in Schemas(single)', () => {
         try {
             const template = getTemplate();
-            template.schemas[0].a.type = 'myText';
-            template.schemas[0].b.type = 'myText';
+            template.schemas[0][0].type = 'myText';
+            template.schemas[0][1].type = 'myText';
             (0, helper_1.checkPlugins)({ template, plugins });
             expect.anything();
         }
@@ -311,8 +319,8 @@ describe('checkPlugins test', () => {
     test('success test: type in Schemas(multiple)', () => {
         try {
             const template = getTemplate();
-            template.schemas[0].a.type = 'myText';
-            template.schemas[0].b.type = 'myImage';
+            template.schemas[0][0].type = 'myText';
+            template.schemas[0][1].type = 'myImage';
             (0, helper_1.checkPlugins)({ template, plugins });
             expect.anything();
         }
@@ -323,8 +331,8 @@ describe('checkPlugins test', () => {
     test('fail test: type in Schemas not found in plugins(single)', () => {
         try {
             const template = getTemplate();
-            template.schemas[0].a.type = 'fail';
-            template.schemas[0].b.type = 'myImage';
+            template.schemas[0][0].type = 'fail';
+            template.schemas[0][1].type = 'myImage';
             (0, helper_1.checkPlugins)({ template, plugins });
             fail();
         }
@@ -335,8 +343,8 @@ describe('checkPlugins test', () => {
     test('fail test: type in Schemas not found in plugins(multiple)', () => {
         try {
             const template = getTemplate();
-            template.schemas[0].a.type = 'fail';
-            template.schemas[0].b.type = 'fail2';
+            template.schemas[0][0].type = 'fail';
+            template.schemas[0][1].type = 'fail2';
             (0, helper_1.checkPlugins)({ template, plugins });
             fail();
         }
@@ -352,22 +360,24 @@ describe('getDynamicTemplate', () => {
     const padding = 10;
     const template = {
         schemas: [
-            {
-                a: {
+            [
+                {
+                    name: 'a',
                     content: 'a',
                     type: 'a',
                     position: { x: 10, y: aPositionY },
                     width: 10,
                     height,
                 },
-                b: {
+                {
+                    name: 'b',
                     content: 'b',
                     type: 'b',
                     position: { x: 10, y: bPositionY },
                     width: 10,
                     height,
                 },
-            },
+            ],
         ],
         basePdf: { width: 100, height: 100, padding: [padding, padding, padding, padding] },
     };
@@ -399,8 +409,10 @@ describe('getDynamicTemplate', () => {
             const dynamicTemplate = await (0, helper_1.getDynamicTemplate)(createGetDynamicTemplateArg(increaseHeights));
             verifyBasicStructure(dynamicTemplate);
             expect(dynamicTemplate.schemas.length).toBe(1);
-            expect(dynamicTemplate.schemas[0].a.position.y).toEqual(aPositionY);
-            expect(dynamicTemplate.schemas[0].b.position.y).toEqual(increaseHeights.reduce((a, b) => a + b, 0) - height + bPositionY);
+            expect(dynamicTemplate.schemas[0][0].position.y).toEqual(aPositionY);
+            expect(dynamicTemplate.schemas[0][0].name).toEqual('a');
+            expect(dynamicTemplate.schemas[0][1].position.y).toEqual(increaseHeights.reduce((a, b) => a + b, 0) - height + bPositionY);
+            expect(dynamicTemplate.schemas[0][1].name).toEqual('b');
         });
     });
     describe('Multiple page scenarios', () => {
@@ -409,19 +421,25 @@ describe('getDynamicTemplate', () => {
             const dynamicTemplate = await (0, helper_1.getDynamicTemplate)(createGetDynamicTemplateArg(increaseHeights));
             verifyBasicStructure(dynamicTemplate);
             expect(dynamicTemplate.schemas.length).toBe(2);
-            expect(dynamicTemplate.schemas[0].a.position.y).toEqual(aPositionY);
-            expect(dynamicTemplate.schemas[0].b).toBeUndefined();
-            expect(dynamicTemplate.schemas[1].b.position.y).toEqual(padding);
+            expect(dynamicTemplate.schemas[0][0].position.y).toEqual(aPositionY);
+            expect(dynamicTemplate.schemas[0][0].name).toEqual('a');
+            expect(dynamicTemplate.schemas[0][1]).toBeUndefined();
+            expect(dynamicTemplate.schemas[1][0].name).toEqual('b');
+            expect(dynamicTemplate.schemas[1][0].position.y).toEqual(padding);
+            expect(dynamicTemplate.schemas[1][1]).toBeUndefined();
         });
         test('should handle page break with a on page 1 and 2, b on page 2', async () => {
             const increaseHeights = [20, 20, 20, 20, 20];
             const dynamicTemplate = await (0, helper_1.getDynamicTemplate)(createGetDynamicTemplateArg(increaseHeights));
             verifyBasicStructure(dynamicTemplate);
             expect(dynamicTemplate.schemas.length).toBe(2);
-            expect(dynamicTemplate.schemas[0].a.position.y).toEqual(aPositionY);
-            expect(dynamicTemplate.schemas[0].b).toBeUndefined();
-            expect(dynamicTemplate.schemas[1].a.position.y).toEqual(padding);
-            expect(dynamicTemplate.schemas[1].b.position.y).toEqual(increaseHeights.slice(3).reduce((a, b) => a + b, 0) - height + padding);
+            expect(dynamicTemplate.schemas[0][0].position.y).toEqual(aPositionY);
+            expect(dynamicTemplate.schemas[0][0].name).toEqual('a');
+            expect(dynamicTemplate.schemas[0][1]).toBeUndefined();
+            expect(dynamicTemplate.schemas[1][0].position.y).toEqual(padding);
+            expect(dynamicTemplate.schemas[1][0].name).toEqual('a');
+            expect(dynamicTemplate.schemas[1][1].position.y).toEqual(increaseHeights.slice(3).reduce((a, b) => a + b, 0) - height + padding);
+            expect(dynamicTemplate.schemas[1][1].name).toEqual('b');
         });
         test('should handle multiple page breaks', async () => {
             const increaseHeights = [50, 50, 50, 50, 50];
@@ -430,15 +448,17 @@ describe('getDynamicTemplate', () => {
             expect(dynamicTemplate.schemas.length).toBe(5);
             // Verify 'a' elements
             for (let i = 0; i < 4; i++) {
-                expect(dynamicTemplate.schemas[i].a).toBeDefined();
-                expect(dynamicTemplate.schemas[i].a.position.y).toEqual(i === 0 ? aPositionY : padding);
-                expect(dynamicTemplate.schemas[i].a.height).toEqual(i === 3 ? 100 : 50);
-                expect(dynamicTemplate.schemas[i].b).toBeUndefined();
+                expect(dynamicTemplate.schemas[i][0]).toBeDefined();
+                expect(dynamicTemplate.schemas[i][0].position.y).toEqual(i === 0 ? aPositionY : padding);
+                expect(dynamicTemplate.schemas[i][0].height).toEqual(i === 3 ? 100 : 50);
+                expect(dynamicTemplate.schemas[i][0].name).toEqual('a');
+                expect(dynamicTemplate.schemas[i][1]).toBeUndefined();
             }
             // Verify 'b' element
-            expect(dynamicTemplate.schemas[4].b).toBeDefined();
-            expect(dynamicTemplate.schemas[4].b.position.y).toEqual(padding);
-            expect(dynamicTemplate.schemas[4].b.height).toEqual(10);
+            expect(dynamicTemplate.schemas[4][0]).toBeDefined();
+            expect(dynamicTemplate.schemas[4][0].name).toEqual('b');
+            expect(dynamicTemplate.schemas[4][0].position.y).toEqual(padding);
+            expect(dynamicTemplate.schemas[4][0].height).toEqual(10);
         });
         test('should handle both a and b on next page', async () => {
             const increaseHeights = [80, 10, 10];
@@ -446,16 +466,16 @@ describe('getDynamicTemplate', () => {
             verifyBasicStructure(dynamicTemplate);
             expect(dynamicTemplate.schemas.length).toBe(2);
             // Check first page
-            expect(dynamicTemplate.schemas[0].a).toBeDefined();
-            expect(dynamicTemplate.schemas[0].a.position.y).toEqual(aPositionY);
-            expect(dynamicTemplate.schemas[0].a.height).toEqual(80);
-            expect(dynamicTemplate.schemas[0].b).toBeUndefined();
+            expect(dynamicTemplate.schemas[0][0]).toBeDefined();
+            expect(dynamicTemplate.schemas[0][0].position.y).toEqual(aPositionY);
+            expect(dynamicTemplate.schemas[0][0].height).toEqual(80);
+            expect(dynamicTemplate.schemas[0][1]).toBeUndefined();
             // Check second page
-            expect(dynamicTemplate.schemas[1].a).toBeDefined();
-            expect(dynamicTemplate.schemas[1].a.position.y).toEqual(padding);
-            expect(dynamicTemplate.schemas[1].a.height).toEqual(20);
-            expect(dynamicTemplate.schemas[1].b).toBeDefined();
-            expect(dynamicTemplate.schemas[1].b.position.y).toBeGreaterThanOrEqual(dynamicTemplate.schemas[1].a.position.y + dynamicTemplate.schemas[1].a.height);
+            expect(dynamicTemplate.schemas[1][0]).toBeDefined();
+            expect(dynamicTemplate.schemas[1][0].position.y).toEqual(padding);
+            expect(dynamicTemplate.schemas[1][0].height).toEqual(20);
+            expect(dynamicTemplate.schemas[1][1]).toBeDefined();
+            expect(dynamicTemplate.schemas[1][1].position.y).toBeGreaterThanOrEqual(dynamicTemplate.schemas[1][0].position.y + dynamicTemplate.schemas[1][0].height);
         });
     });
     describe('Element height modifications', () => {
@@ -466,14 +486,15 @@ describe('getDynamicTemplate', () => {
             verifyBasicStructure(dynamicTemplate);
             expect(dynamicTemplate.schemas.length).toBe(2);
             // Check 'a' element
-            expect(dynamicTemplate.schemas[0].a).toBeDefined();
-            expect(dynamicTemplate.schemas[0].a.position.y).toEqual(aPositionY);
-            expect(dynamicTemplate.schemas[0].a.height).toEqual(50);
+            expect(dynamicTemplate.schemas[0][0]).toBeDefined();
+            expect(dynamicTemplate.schemas[0][0].position.y).toEqual(aPositionY);
+            expect(dynamicTemplate.schemas[0][0].height).toEqual(50);
+            expect(dynamicTemplate.schemas[0][0].name).toEqual('a');
             // Check 'b' element
-            const bSchema = dynamicTemplate.schemas.find((schema) => schema.b);
-            expect(bSchema).toBeDefined();
-            expect(bSchema.b.position.y).toEqual(padding);
-            expect(bSchema.b.height).toEqual(bHeight);
+            expect(dynamicTemplate.schemas[1][0]).toBeDefined();
+            expect(dynamicTemplate.schemas[1][0].position.y).toEqual(padding);
+            expect(dynamicTemplate.schemas[1][0].height).toEqual(bHeight);
+            expect(dynamicTemplate.schemas[1][0].name).toEqual('b');
         });
     });
     describe('Edge cases', () => {
@@ -482,8 +503,9 @@ describe('getDynamicTemplate', () => {
             const dynamicTemplate = await (0, helper_1.getDynamicTemplate)(createGetDynamicTemplateArg(increaseHeights));
             verifyBasicStructure(dynamicTemplate);
             expect(dynamicTemplate.schemas.length).toBe(1);
-            expect(dynamicTemplate.schemas[0].a).toBeUndefined();
-            expect(dynamicTemplate.schemas[0].b).toBeDefined();
+            expect(dynamicTemplate.schemas[0][0]).toBeDefined();
+            expect(dynamicTemplate.schemas[0][0].name).toEqual('b');
+            expect(dynamicTemplate.schemas[0][1]).toBeUndefined();
         });
         test('should handle very large increase heights', async () => {
             const increaseHeights = [1000, 1000];
@@ -493,4 +515,133 @@ describe('getDynamicTemplate', () => {
         });
     });
 });
+describe('migrateTemplate', () => {
+    it('should convert LegacySchemaPageArray to SchemaPageArray', () => {
+        const legacyTemplate = {
+            schemas: [
+                {
+                    "field1": {
+                        "type": "text",
+                        "content": "Field 1",
+                        "width": 45,
+                        "height": 10,
+                        "position": {
+                            "x": 0,
+                            "y": 0
+                        }
+                    },
+                    "field2": {
+                        "type": "text",
+                        "content": "Field 2",
+                        "width": 45,
+                        "height": 10,
+                        "position": {
+                            "x": 0,
+                            "y": 0
+                        }
+                    }
+                },
+                {
+                    "field3": {
+                        "type": "text",
+                        "content": "Field 3",
+                        "width": 45,
+                        "height": 10,
+                        "position": {
+                            "x": 0,
+                            "y": 0
+                        }
+                    }
+                }
+            ]
+        };
+        (0, helper_1.migrateTemplate)(legacyTemplate);
+        const expectedSchemaPageArray = [
+            [
+                {
+                    "name": "field1",
+                    "type": "text",
+                    "content": "Field 1",
+                    "width": 45,
+                    "height": 10,
+                    "position": {
+                        "x": 0,
+                        "y": 0
+                    }
+                },
+                {
+                    "name": "field2",
+                    "type": "text",
+                    "content": "Field 2",
+                    "width": 45,
+                    "height": 10,
+                    "position": {
+                        "x": 0,
+                        "y": 0
+                    }
+                }
+            ],
+            [
+                {
+                    "name": "field3",
+                    "type": "text",
+                    "content": "Field 3",
+                    "width": 45,
+                    "height": 10,
+                    "position": {
+                        "x": 0,
+                        "y": 0
+                    }
+                }
+            ]
+        ];
+        expect(legacyTemplate.schemas).toEqual(expectedSchemaPageArray);
+    });
+    it('should not modify already SchemaPageArray', () => {
+        const pagedTemplate = {
+            schemas: [
+                [
+                    {
+                        "name": "field1",
+                        "type": "text",
+                        "content": "Field 1",
+                        "width": 45,
+                        "height": 10,
+                        "position": {
+                            "x": 0,
+                            "y": 0
+                        }
+                    },
+                    {
+                        "name": "field2",
+                        "type": "text",
+                        "content": "Field 2",
+                        "width": 45,
+                        "height": 10,
+                        "position": {
+                            "x": 0,
+                            "y": 0
+                        }
+                    }
+                ],
+                [
+                    {
+                        "name": "field3",
+                        "type": "text",
+                        "content": "Field 3",
+                        "width": 45,
+                        "height": 10,
+                        "position": {
+                            "x": 0,
+                            "y": 0
+                        }
+                    }
+                ]
+            ]
+        };
+        const before = JSON.parse(JSON.stringify(pagedTemplate));
+        (0, helper_1.migrateTemplate)(pagedTemplate);
+        expect(pagedTemplate.schemas).toEqual(before.schemas);
+    });
+});
 //# sourceMappingURL=helper.test.js.map