v3 (#344)

* Code refactoring * Fetch changes from master * [SVG] WIP * [SVG] Finish SVG rendering * Fix tests * Finished es modules and prebuilt bundle * [SVG] Add scissors * [doc] Update documentation * Remove tests for windows * Improve feature exports * Update API * [doc] Mention node 13 * Release v3.0.0-beta.2 * [types] re-export pdf types * export features by path * Remove extension from feature exports * Finally got working exports 🚀 * [ci] Remove build * Change target to ES6 * [doc] Add missing links in navigation * [Readme] Add link to unpkg * [Readme] Code cleanup * [Readme] Add example for svg * Code cleanup * Release v3.0.0
schoero · Oct 3, 2021 · 4df7b66 · 4df7b66
1 parent ebab157
commit 4df7b66
Show file tree

Hide file tree

Showing 85 changed files with 5,411 additions and 3,349 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -16,4 +16,3 @@ jobs:
       run: |
         npm ci
         npm test
-        npm run build
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -4,5 +4,8 @@
   },
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": true
-  }
+  },
+  "javascript.preferences.importModuleSpecifierEnding": "js",
+  "typescript.preferences.importModuleSpecifierEnding": "js",
+  "liveServer.settings.port": 5501
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,33 @@
 
 # Change Log
 
+# [v3.0.0](https://github.com/schoero/swissqrbill/compare/v2.4.2...v3.0.0) - 03.10.2021
+  * New features
+    * SVG
+      * Added support for SVG rendering [#343](https://github.com/schoero/SwissQRBill/issues/343).
+    * Added es6 module exports.
+    * Support for tree shaking.
+    * utils
+      * Added `mm2px()` function.
+      * Added `px2mm()` function.
+      * Added `pt2mm()` function.
+  * Breaking changes
+    * imports
+      * SwissQRBill is now available as a CommonJS and an ES module. This may change how the module has to be imported. Please take a look at the [importing the library](https://github.com/schoero/SwissQRBill#importing-the-library) section in the readme.
+    * data
+      * the field `houseNumber` has been renamed to `buildingNumber`.
+      * the deprecated field `debitor` has been removed. Use `debtor` instead.
+    * utils
+      * `mmToPoints()` function has been renamed to `mm2pt()`.
+    * PDF
+      * Removed deprecated `mmToPoints()` export. Use `utils.mm2pt()` instead.
+  * Fixes
+    * PDF
+      * The positioning of the box when no amount is provided has been slightly corrected.
+      * The positioning iban on the payment part has been slightly corrected.
+      * Fixed positioning of the debtor boxes when no debtor is provided and the creditor address break to multiple lines.
+
+
 # [v2.4.2](https://github.com/schoero/swissqrbill/compare/v2.4.1...v2.4.2) - 26.08.2021
   * Fixed translation of `additionalInformation` and `payableByName`. [#342](https://github.com/schoero/SwissQRBill/pull/342)
 

diff --git a/README.md b/README.md
@@ -37,10 +37,14 @@ With SwissQRBill you can easily generate the new QR Code payment slips in Node.j
 [<img src="https://raw.githubusercontent.com/schoero/SwissQRBill/master/assets/qrbill.png">](https://github.com/schoero/SwissQRBill/blob/master/assets/qrbill.pdf)
 
 
+<br/>
+<br/>
+
 ## Links
 
  * [Features](#features)
  * [Installation](#installation)
+ * [Importing the library](#importing-the-library)
  * [Quick start](#quick-start)
  * [Browser usage](#browser-usage)
  * [API documentation](https://github.com/schoero/SwissQRBill/blob/master/doc/api.md)
@@ -50,28 +54,89 @@ With SwissQRBill you can easily generate the new QR Code payment slips in Node.j
  * [QR bill specifications](https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-en.pdf)
 
 
+<br/>
+
 ## Features
- - Generates PDF with scalable vector graphics
- - Works in browser and node
- - Supports german, english, italian and french invoices
- - Supports A4 invoices as well as A6/5 (QR bill only)
- - Allows you to add other content above the invoice using [PDFKit](https://github.com/foliojs/pdfkit)
- - Easy to use
- - Free and open source
+ - Generate complete invoices, or only the QR Bill, as a PDF file.
+ - Generate the QR Bill as a scalable vector graphic (SVG).
+ - Works in browsers and Node.js.
+ - Supports german, english, italian and french invoices.
+ - Allows you to add other content above the invoice using [PDFKit](https://github.com/foliojs/pdfkit).
+ - Easy to use.
+ - Free and open source.
 
+<br/>
 
 ## Installation
 
 ```
 npm i swissqrbill --save
 ```
 
+<br/>
+
+## Importing the library
+
+### Node.js
+
+In versions prior to v3.0.0, you could simply include SwissQRBill like this:
+
+```js
+const SwissQRBill = require("swissqrbill"); // CommonJS. Not tree-shakeable.
+```
+
+<br/>
+
+While you can still do this, it is recommended to switch to the new ES module imports to be able to take advantage of tree-shaking. SwissQRBill uses the new [conditional exports feature](https://nodejs.org/api/packages.html#packages_exports_sugar) that was added in node v12.16.0 or v13.6.0.
+
+This allows you to import only the parts of SwissQRBill that you actually need.
+
+```js
+import { PDF } from "swissqrbill/pdf"; // ESM. Tree-shakeable
+import { SVG } from "swissqrbill/svg"; // ESM. Tree-shakeable
+import { mm2pt } from "swissqrbill/utils"; // ESM. Tree-shakeable
+```
+
+<br/>
+
+Unfortunately, TypeScript with a version prior to the upcoming [version 4.5](https://github.com/microsoft/TypeScript/issues/45418), and Node.js prior to v12.16.0 or v13.6.0, do not support this feature.
+If you are using a TypeScript or Node.js version, that doesn't support the new export feature, you can still take advantage of tree-shaking, by importing the files directly by their path.
+
+```js
+import { PDF } from "swissqrbill/lib/node/esm/node/pdf.js"; // ESM. Tree-shakeable
+import { SVG } from "swissqrbill/lib/node/esm/node/svg.js"; // ESM. Tree-shakeable
+import { mm2pt } from "swissqrbill/lib/node/esm/shared/utils.js"; // ESM. Tree-shakeable
+```
+
+<br/>
+
+### Browser
+
+For the browser it is a bit more complicated. The easiest way would be to include the pre-bundled version.
+
+```html
+<script type="text/javascript" src="https://unpkg.com/swissqrbill/lib/browser/bundle/index.js" />
+```
+
+You can also import the bundle directly, if you are using a bundler like webpack.
+
+```js
+import SwissQRBill from "swissqrbill/lib/browser/bundle";
+```
+
+However, if you want to take advantage of tree-shaking in the browser, you have to bundle the library by yourself.
+You can find an example, how this could be done using webpack, at https://github.com/schoero/SwissQRBill-browser-example.
+
+
+<br/>
+<br/>
+
 ## Quick start
 
-It's quite easy to create a simple QR bill. All you have to do is create a new `SwissQRBill.PDF` instance and pass your billing data object as the first parameter and your output path as the second parameter.
+Once you have imported SwissQRBill, it is quite easy to create a simple QR bill. All you have to do is to create a new `SwissQRBill.PDF` instance and pass your billing data object as the first parameter and your output path as the second parameter.
 
 ```js
-const SwissQRBill = require("swissqrbill");
+import { PDF } from "swissqrbill/pdf";
 
 const data = {
   currency: "CHF",
@@ -94,24 +159,28 @@ const data = {
   }
 };
 
-const pdf = new SwissQRBill.PDF(data, "qrbill.pdf", () => {
+const pdf = new PDF(data, "qrbill.pdf", () => {
   console.log("PDF has been successfully created.");
 });
 ```
 
-This will create the above PDF file. You can pass an optional third parameter containing options such as language or size etc. as well as a callback function that gets called right after the file has finished writing.
+This will create the PDF file above. You can pass an optional third parameter containing options such as language or size etc. as well as a callback function that gets called right after the file has finished writing.
 A complete documentation for all methods and parameters can be found in [doc/api.md](https://github.com/schoero/SwissQRBill/blob/master/doc/api.md).
 
+<br/>
 <br/>
 
 ## Browser usage
 
+> **Note:** Please read the [importing the library](#importing-the-library) section above, how you should import the library for browser usage.
+
 To use SwissQRBill inside browsers, you have to pass a writableStream in the second parameter, instead of the output path. To create a writableStream in the browser you can use the built in `SwissQRBill.BlobStream()` function.
 
 ```js
-const stream = new SwissQRBill.BlobStream();
+import { PDF, BlobStream } from "swissqrbill/pdf";
 
-const pdf = new SwissQRBill.PDF(data, stream);
+const stream = new BlobStream();
+const pdf = new PDF(data, stream);
 
 pdf.on("finish", () => {
   const iframe = document.getElementById("iframe");
@@ -122,13 +191,20 @@ pdf.on("finish", () => {
 });
 ```
 
-You can see a fully working example at https://github.com/schoero/SwissQRBill-browser-example.
+Alternatively, you could render the QR Bill as a scalable vector graphic (SVG). But keep in mind, using SVG you can only render the QR Bill part and not an entire invoice.
+
+```js
+import { SVG } from "swissqrbill/svg";
 
+const svg = new SVG(data);
+document.body.appendChild(svg.element);
+```
+<br/>
 <br/>
 
 ## Further informations
 
-SwissQRBill extends [PDFKit](https://github.com/foliojs/pdfkit) to generate PDF files and adds a few extra methods. You can generate a complete PDF bill using the original PDFKit methods and the additional methods documented in [doc/api.md](https://github.com/schoero/SwissQRBill/tree/master/doc/api.md#methods).
+SwissQRBill.PDF extends [PDFKit](https://github.com/foliojs/pdfkit) to generate PDF files and adds a few extra methods. You can generate a complete PDF bill using the original PDFKit methods and the additional methods documented in [doc/api.md](https://github.com/schoero/SwissQRBill/tree/master/doc/api.md#methods).
 The documentation for PDFKit can be found [here](http://pdfkit.org/docs/getting_started.html).
 
 A simple guide how to generate a complete bill can be found in [doc/how-to-create-a-complete-bill.md](https://github.com/schoero/SwissQRBill/blob/master/doc/how-to-create-a-complete-bill.md). You will learn how to create a PDF that looks like this:

diff --git a/doc/api.md b/doc/api.md
@@ -16,6 +16,17 @@
 
 <br/>
 
+# SwissQRBill.SVG
+
+- Constructor
+  - [SwissQRBill.SVG(data[, options])](#swissqrbillsvgdata-options)
+- Methods
+  - [toString()](#tostring)
+- Getters
+  - [element](#element)
+
+<br/>
+
 # SwissQRBill.BlobStream
 
 - Constructor
@@ -42,7 +53,10 @@
   - Amount
     - [formatAmount(amount)](#formatamountamount)
   - Other
-    - [mmToPoints(mm)](#mmtopointsmm)
+    - [mm2pt(millimeters)](#mm2ptmillimeters)
+    - [pt2mm(points)](#pt2mmpoints)
+    - [mm2px(millimeters)](#mm2pxmillimeters)
+    - [px2mm(pixels)](#px2mmpixels)
 
 
 <br/>
@@ -85,21 +99,21 @@
       > First name + last name or company name.
     - **account** - `string` *mandatory*, 21 characters.
     - **address** - `string` *mandatory*, max 70 characters.
-    - **houseNumber** - `string | number` *optional*, max 16 characters.
+    - **buildingNumber** - `string | number` *optional*, max 16 characters.
     - **zip** - `number | string` *mandatory*, max 16 characters.
     - **city** - `string` *mandatory*, max 35 characters.
     - **country** - `string` *mandatory*, 2 characters.
   - **debtor** *optional*
     - **name** - `string` *mandatory*, max. 70 characters.
       > First name + last name or company name.
     - **address** - `string` *mandatory*, max 70 characters.
-    - **houseNumber** - `string | number` *optional*, max 16 characters.
+    - **buildingNumber** - `string | number` *optional*, max 16 characters.
     - **zip** - `number | string` *mandatory*, max 16 characters.
     - **city** - `string` *mandatory*, max 35 characters.
     - **country** - `string` *mandatory*, 2 characters.
 
 
-#### options
+##### options
 
   Available options: 
 
@@ -128,7 +142,7 @@ const data = {
   creditor: {
     name: "Robert Schneider AG",
     address: "Rue du Lac",
-    houseNumber: "1268",
+    buildingNumber: "1268",
     zip: 2501,
     city: "Biel",
     account: "CH4431999123000889012",
@@ -137,7 +151,7 @@ const data = {
   debtor: {
     name: "Pia-Maria Rutschmann-Schnyder",
     address: "Grosse Marktgasse",
-    houseNumber: 28,
+    buildingNumber: 28,
     zip: 9400,
     city: "Rorschach",
     country: "CH"
@@ -244,6 +258,45 @@ This could be used to add page numbers to the pages as described [here](http://p
 
 <br/>
 
+
+# SwissQRBill.SVG
+## Constructor
+
+#### SwissQRBill.SVG(data[, options])
+
+ - [**data**](#data-1) - `object` containing all relevant billing data, *mandatory*.
+ - [**options**](#options-1) - `object` containing settings, *optional*.
+
+##### data
+
+  The data object is the same as the [data object](#data) in the PDF constructor above.
+
+##### options
+
+  Available options: 
+
+   - **language** - `string: "DE" | "EN" | "IT" | "FR"`. *default* `"DE"`.
+
+<br/>
+
+## Methods
+
+### toString()
+Returns the outerHTML of the SVG.
+<br/>
+
+## Getters
+
+### element
+Returns the SVG element.
+> **Note:** This function is only available in the browser.
+
+```js
+const svg = new SVG(data);
+document.body.appendChild(svg.element);
+```
+<br/>
+
 # SwissQRBill.BlobStream
 
 ## Constructor
@@ -333,7 +386,22 @@ Returns a `string` containing the formatted amount.
 
 ### Other
 
-#### mmToPoints(mm)
- - mm - `number` containg the millimeters you want to convert to points.  
+#### mm2pt(millimeters)
+ - millimeters - `number` containg the millimeters you want to convert to points.  
  Converts milimeters to points. This method can be used to simplify positioning while you create your own layout using PDFKit.  
  Returns a `number` containing the converted millimeters in points.
+
+#### pt2mm(points)
+ - points - `number` containg the points you want to convert to millimeters.  
+ Converts points to millimeters. This method can be used to simplify positioning while you create your own layout using PDFKit.  
+ Returns a `number` containing the converted points in millimeters.
+
+#### mm2px(millimeters)
+ - millimeters - `number` containg the millimeters you want to convert to pixels.  
+ Converts milimeters to pixels. This method can be used to simplify positioning while you create your own layout using PDFKit.  
+ Returns a `number` containing the converted millimeters in pixels.
+
+#### px2mm(pixels)
+ - pixels - `number` containg the pixels you want to convert to millimeters.  
+ Converts pixels to millimeters. This method can be used to simplify positioning while you create your own layout using PDFKit.
+ Returns a `number` containing the converted pixels in millimeters.
-Original file line number
+Diff line change
@@ Expand Up / @@ -16,4 +16,3 @@ jobs: @@
           run: |
             npm ci
             npm test
-            npm run build