qr-code-styling-node 1.6.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -31,7 +31,7 @@ npm install qr-code-styling-node
31
31
  <head>
32
32
  <meta charset="UTF-8">
33
33
  <title>QR Code Styling</title>
34
- <script type="text/javascript" src="https://unpkg.com/qr-code-styling-node@1.6.0/lib/qr-code-styling.js"></script>
34
+ <script type="text/javascript" src="https://unpkg.com/qr-code-styling-node@1.8.0/lib/qr-code-styling.js"></script>
35
35
  </head>
36
36
  <body>
37
37
  <div id="canvas"></div>
@@ -77,6 +77,57 @@ The package ships an ES module build (`import`), a CommonJS/UMD build (`require`
77
77
 
78
78
  ---
79
79
 
80
+ ### QR art
81
+
82
+ <img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/art_examples.png" width="720" />
83
+
84
+ Blend a picture into the code with `art`. Two modes:
85
+
86
+ - `halftone` (default): the picture is redrawn as fine pixels, with each QR module kept in the middle. Use `colored: true` to keep the picture's colors.
87
+ - `colorize`: dots keep their shape (any `dotsOptions.type`) and are painted with a darkened copy of the picture, over a light copy of it.
88
+
89
+ ```js
90
+ const qrCode = new QRCodeStyling({
91
+ data: "https://example.com",
92
+ qrOptions: { errorCorrectionLevel: "H" }, // recommended for art
93
+ art: { image: "https://example.com/photo.jpg", mode: "halftone", colored: true },
94
+ imageOptions: { crossOrigin: "anonymous" } // the picture must be readable by a canvas
95
+ });
96
+ ```
97
+
98
+ QR art reads the picture's pixels, so it needs a canvas: it works as is in the browser, and on Node it needs
99
+ `nodeCanvas`. Pictures from another origin need CORS (`crossOrigin`), or the browser will block reading them.
100
+
101
+ `art` structure
102
+
103
+ Property |Type |Default Value|Description
104
+ ----------|----------------------------------|-------------|------------------------------------------------------------
105
+ image |string | |The picture (URL or data URL). Required
106
+ mode |string (`'halftone' 'colorize'`) |`'halftone'` |How the picture is blended in
107
+ colored |boolean |`false` |halftone: use the picture's colors instead of dots/background colors
108
+ background|boolean |`true` |colorize: show a light copy of the picture behind the dots
109
+ contrast |number (`0 - 1`) |`0.5` halftone, `0.7` colorize|Higher is easier to scan but shows less of the picture
110
+ crossOrigin|string | |Overrides `imageOptions.crossOrigin` for the picture
111
+
112
+ ### Checking that a code scans
113
+
114
+ `verify()` renders the code and decodes it with a QR decoder you pass in, so the library itself stays dependency-free.
115
+ It works with any decoder that has the [jsQR](https://www.npmjs.com/package/jsqr) signature.
116
+
117
+ ```js
118
+ import jsQR from "jsqr";
119
+
120
+ const result = await qrCode.verify({ decoder: jsQR });
121
+ // { readable: true, decoded: "https://example.com", attempts: 1 }
122
+
123
+ // For QR art: raise art.contrast step by step until the code scans, and keep that setting.
124
+ const tuned = await qrCode.verify({ decoder: jsQR, adjust: true });
125
+ // { readable: true, decoded: "...", contrast: 0.8, attempts: 3 }
126
+ ```
127
+
128
+ On Node, `verify()` needs `nodeCanvas` or `resvg` to draw the code. A decoder succeeding is a good sign, not a
129
+ guarantee: phone cameras are usually more forgiving than jsQR, but print size, light and screen glare matter too.
130
+
80
131
  ### API Documentation
81
132
 
82
133
  #### QRCodeStyling instance
@@ -102,8 +153,10 @@ dotsOptions |object | |Dots styling opt
102
153
  cornersSquareOptions |object | |Square in the corners styling options
103
154
  cornersDotOptionsHelper|object | |Dots in the corners styling options
104
155
  backgroundOptions |object | |QR background styling options
105
- nodeCanvas |node-canvas | |Only specify when running on a node server for canvas type, please refer to node section below
106
- jsDom |jsdom | |Only specify when running on a node server for svg type, please refer to node section below
156
+ nodeCanvas |node-canvas | |Node only, optional. Needed for canvas output (png, jpeg, webp) on a server, see the Node section below
157
+ jsdom |jsdom | |Node only, optional. Not needed for svg any more; still accepted for backward compatibility
158
+ resvg |`Resvg` from `@resvg/resvg-js`| |Node only, optional. Produces png without node-canvas, see the Node section below
159
+ art |object | |Blend a picture into the code, see "QR art" above
107
160
 
108
161
  `options.qrOptions` structure
109
162
 
@@ -200,6 +253,13 @@ Param |Type |Default Value|Description
200
253
  ---------|------------------------------------|-------------|------------
201
254
  extension|string (`'png' 'jpeg' 'webp' 'svg'`)|`'png'` |Blob type on browser, Buffer type on Node
202
255
 
256
+ `QRCodeStyling.verify({ decoder, adjust }) => Promise<{ readable, decoded, contrast, attempts }>`
257
+
258
+ Param |Type |Description
259
+ -------|--------|--------------------------------------------------------------
260
+ decoder|function|A QR decoder with the jsQR signature `(rgba, width, height) => { data } \| null`
261
+ adjust |boolean |For QR art: raise `art.contrast` until the code scans. Default `false`
262
+
203
263
  `QRCodeStyling.update(options) => void`
204
264
 
205
265
  Param |Type |Description
@@ -222,9 +282,47 @@ name |string |`'qr'` |Name of the downloa
222
282
  extension|string (`'png' 'jpeg' 'webp' 'svg'`)|`'png'` |File extension
223
283
 
224
284
  ### Node Support
225
- You can use this on a node server by passing through the node-canvas or jsdom object depending if your creating a non-svg or svg respectively. You must pass both if using `imageOptions.saveAsBlob`.
226
285
 
227
- Calling `getRawData` in node will return a Buffer instead of a Blob.
286
+ #### SVG with no extra packages
287
+
288
+ On Node.js, SVG output works out of the box: no `jsdom` and no `canvas` are needed, and it is about
289
+ 6 times faster than going through jsdom. `getRawData` returns a Buffer on Node (a Blob where `Buffer` does not exist).
290
+ Other runtimes without a DOM should work the same way, but only Node.js is tested.
291
+
292
+ ```js
293
+ const QRCodeStyling = require("qr-code-styling-node");
294
+ const fs = require("fs");
295
+
296
+ const qrCode = new QRCodeStyling({
297
+ type: "svg",
298
+ data: "https://example.com",
299
+ image: "https://example.com/logo.png", // data URLs and http(s) URLs work; remote images use fetch
300
+ dotsOptions: { color: "#4267b2", type: "rounded" },
301
+ imageOptions: { saveAsBlob: true, margin: 8 } // saveAsBlob embeds the logo inside the SVG
302
+ });
303
+
304
+ qrCode.getRawData("svg").then((buffer) => fs.writeFileSync("qr.svg", buffer));
305
+ ```
306
+
307
+ #### PNG without node-canvas
308
+
309
+ `node-canvas` needs native system libraries. If you only need png, install `@resvg/resvg-js` instead
310
+ (prebuilt binaries, nothing to compile) and pass its `Resvg` class:
311
+
312
+ ```js
313
+ const QRCodeStyling = require("qr-code-styling-node");
314
+ const { Resvg } = require("@resvg/resvg-js");
315
+ const fs = require("fs");
316
+
317
+ const qrCode = new QRCodeStyling({ data: "https://example.com", resvg: Resvg });
318
+ qrCode.getRawData("png").then((buffer) => fs.writeFileSync("qr.png", buffer));
319
+ ```
320
+
321
+ #### With node-canvas (png, jpeg, webp) and jsdom
322
+
323
+ This is the original 1.5.0 way and keeps working unchanged.
324
+ Pass the node-canvas module for canvas output. Passing `jsdom` for svg is optional now.
325
+ You must pass both if using `imageOptions.saveAsBlob` with jsdom.
228
326
 
229
327
  `canvas` and `jsdom` are not dependencies of this package; install the ones you need (`npm install canvas jsdom`).
230
328
 
@@ -0,0 +1,51 @@
1
+ /**
2
+ * QR art: blends a picture into the QR code while keeping it scannable.
3
+ *
4
+ * Both renderers (canvas and SVG) share this module. It reads the picture through a canvas
5
+ * (the browser's, or node-canvas on Node) and returns plain shapes and images to draw.
6
+ */
7
+ import { RequiredOptions } from "../core/QROptions";
8
+ import { ArtOptions, Canvas, FilterFunction, QRCode } from "../types";
9
+ type RGB = [number, number, number];
10
+ export interface ArtRect {
11
+ x: number;
12
+ y: number;
13
+ width: number;
14
+ height: number;
15
+ color: string;
16
+ }
17
+ export interface QRArea {
18
+ count: number;
19
+ dotSize: number;
20
+ x: number;
21
+ y: number;
22
+ }
23
+ export interface HalftoneArt {
24
+ mode: "halftone";
25
+ rects: ArtRect[];
26
+ }
27
+ export interface ColorizeArt {
28
+ mode: "colorize";
29
+ /** Full-size canvas holding a darkened copy of the picture inside the QR area, used to paint the dots. */
30
+ dots: Canvas;
31
+ /** Full-size canvas holding a light copy of the picture, drawn behind the dots (when art.background). */
32
+ background?: Canvas;
33
+ }
34
+ export type PreparedArt = HalftoneArt | ColorizeArt;
35
+ /** Default contrast per mode: colorize keeps the dot shapes, so it needs more contrast to scan reliably. */
36
+ export declare const DEFAULT_CONTRAST: {
37
+ halftone: number;
38
+ colorize: number;
39
+ };
40
+ export declare const getContrast: (art: ArtOptions) => number;
41
+ /** Luminance limits for "dark" and "light" pixels at a given contrast. */
42
+ export declare const getLimits: (contrast: number) => {
43
+ dark: number;
44
+ light: number;
45
+ };
46
+ export declare const toDark: (color: RGB, limit: number) => RGB;
47
+ export declare const toLight: (color: RGB, limit: number) => RGB;
48
+ export declare function createCanvas(options: RequiredOptions, width: number, height: number): Canvas;
49
+ export declare function getQRArea(options: RequiredOptions, count: number): QRArea;
50
+ export declare function prepareArt(options: RequiredOptions, qr: QRCode, filter: FilterFunction): Promise<PreparedArt>;
51
+ export {};
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Which modules of a QR symbol are function patterns (finders, timing, alignment, format and
3
+ * version information). QR art leaves these solid so scanners can still locate and read the code.
4
+ */
5
+ export type ModuleRole = "finder" | "function" | "data";
6
+ /** Returns a lookup of module roles for a symbol with `count` modules per side. */
7
+ export default function getModuleRoles(count: number): (row: number, col: number) => ModuleRole;
@@ -1,10 +1,13 @@
1
1
  import { RequiredOptions } from "./QROptions";
2
+ import { ArtRect } from "../art/art";
2
3
  import { QRCode, Gradient, FilterFunction, Canvas } from "../types";
3
4
  export default class QRCanvas {
4
5
  _canvas: Canvas;
5
6
  _options: RequiredOptions;
6
7
  _qr?: QRCode;
7
8
  _image?: HTMLImageElement;
9
+ /** Fill used for the dots instead of their color (QR art "colorize"). */
10
+ _dotsFill?: CanvasPattern;
8
11
  constructor(options: RequiredOptions);
9
12
  get context(): CanvasRenderingContext2D | null;
10
13
  get width(): number;
@@ -14,6 +17,7 @@ export default class QRCanvas {
14
17
  drawQR(qr: QRCode): Promise<void>;
15
18
  drawBackground(): void;
16
19
  drawDots(filter?: FilterFunction): void;
20
+ _drawArtRects(rects: ArtRect[]): void;
17
21
  drawCorners(filter?: FilterFunction): void;
18
22
  loadImage(): Promise<void>;
19
23
  drawImage({ width, height, count, dotSize }: {
@@ -1,7 +1,7 @@
1
1
  import QRCanvas from "./QRCanvas";
2
2
  import QRSVG from "./QRSVG";
3
3
  import { RequiredOptions } from "./QROptions";
4
- import { Extension, QRCode, Options, DownloadOptions } from "../types";
4
+ import { Extension, QRCode, Options, DownloadOptions, VerifyOptions, VerifyResult } from "../types";
5
5
  export default class QRCodeStyling {
6
6
  _options: RequiredOptions;
7
7
  _container?: HTMLElement;
@@ -11,10 +11,36 @@ export default class QRCodeStyling {
11
11
  _canvasDrawingPromise?: Promise<void>;
12
12
  _svgDrawingPromise?: Promise<void>;
13
13
  constructor(options?: Partial<Options>);
14
+ /** Canvas output needs a browser canvas or node-canvas. */
15
+ _canUseCanvas(): boolean;
14
16
  static _clearContainer(container?: HTMLElement): void;
15
17
  _getQRStylingElement(extension?: Extension): Promise<QRCanvas | QRSVG>;
16
18
  update(options?: Partial<Options>): void;
17
19
  append(container?: HTMLElement): void;
20
+ static _serializeSVG(svg: QRSVG): string;
21
+ _getSVGString(): Promise<{
22
+ svgString: string;
23
+ svg: QRSVG;
24
+ }>;
25
+ /**
26
+ * resvg follows the SVG spec more strictly than browsers: it does not accept quoted url('#id')
27
+ * references, and it hides elements whose clip-path points to a missing id. Browsers ignore both,
28
+ * so normalize them to get the picture a browser would show. The public SVG output is unchanged.
29
+ */
30
+ static _normalizeSVGForResvg(svgString: string): string;
31
+ _rasterizeWithResvg(extension: Extension): Promise<Buffer | Uint8Array>;
32
+ /** Draws the current QR code to RGBA pixels, using a canvas or, failing that, resvg. */
33
+ _getPixels(): Promise<{
34
+ data: Uint8ClampedArray;
35
+ width: number;
36
+ height: number;
37
+ }>;
38
+ _decode(decoder: VerifyOptions["decoder"]): Promise<string | undefined>;
39
+ /**
40
+ * Checks that the QR code can be scanned by decoding the rendered picture.
41
+ * With `adjust: true` and QR art, raises art.contrast step by step until it scans.
42
+ */
43
+ verify({ decoder, adjust }: VerifyOptions): Promise<VerifyResult>;
18
44
  getRawData(extension?: Extension): Promise<Blob | Buffer | null>;
19
45
  download(downloadOptions?: Partial<DownloadOptions> | string): Promise<void>;
20
46
  }
@@ -1,4 +1,5 @@
1
1
  import { RequiredOptions } from "./QROptions";
2
+ import { ArtRect } from "../art/art";
2
3
  import { QRCode, FilterFunction, Gradient, Window, Canvas } from "../types";
3
4
  export default class QRSVG {
4
5
  _canvas?: Canvas;
@@ -12,6 +13,10 @@ export default class QRSVG {
12
13
  _qr?: QRCode;
13
14
  _image?: HTMLImageElement;
14
15
  _imageUri?: string;
16
+ /** True when no browser DOM or jsdom is available and the built-in virtual DOM is used. */
17
+ _virtual: boolean;
18
+ /** Image used to paint the dots instead of their color (QR art "colorize"). */
19
+ _dotsImageHref?: string;
15
20
  constructor(options: RequiredOptions);
16
21
  get width(): number;
17
22
  get height(): number;
@@ -21,7 +26,10 @@ export default class QRSVG {
21
26
  drawBackground(): void;
22
27
  drawDots(filter?: FilterFunction): void;
23
28
  drawCorners(): void;
29
+ _drawArtRects(rects: ArtRect[]): void;
30
+ _appendImage(href: string, x: number, y: number): void;
24
31
  imageToBlob(): void;
32
+ _loadImageWithoutDom(): Promise<void>;
25
33
  loadImage(): Promise<void>;
26
34
  drawImage({ width, height, count, dotSize }: {
27
35
  width: number;
@@ -29,7 +37,8 @@ export default class QRSVG {
29
37
  count: number;
30
38
  dotSize: number;
31
39
  }): void;
32
- _createColor({ options, color, additionalRotation, x, y, height, width, name }: {
40
+ _createColor({ options, color, additionalRotation, x, y, height, width, name, imageHref }: {
41
+ imageHref?: string;
33
42
  options?: Gradient;
34
43
  color?: string;
35
44
  additionalRotation: number;