qr-code-styling-node 1.11.0 → 1.13.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
@@ -118,6 +118,25 @@ fontSize |number |7% of the size |In p
118
118
  fontFamily|string |`'Helvetica, Arial, sans-serif'` |
119
119
  fontWeight|string or number |`'bold'` |
120
120
 
121
+ ### Connected and decorative dots
122
+
123
+ <img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/dot_examples.png" width="720" />
124
+
125
+ `fluid` joins neighbouring dots into soft strokes, `wave` chains each row into soft beads, `blob` gives every
126
+ module its own hand-drawn corners, and `circuit` draws round pads with thin traces to their neighbours. With
127
+ these four, finders and alignment patterns are drawn solid and rounded (unless you set a corner type), so the
128
+ code keeps scanning.
129
+
130
+ ### Smaller SVG files
131
+
132
+ `svgOptions: { mergePaths: true }` draws all dots as one `<path>` instead of one element per module (and does
133
+ the same for finders drawn with dots). The picture is the same; files are 15-50% smaller and render faster,
134
+ which helps when a page shows many codes.
135
+
136
+ ```js
137
+ new QRCodeStyling({ type: "svg", data: "https://example.com", svgOptions: { mergePaths: true } });
138
+ ```
139
+
121
140
  ### QR art
122
141
 
123
142
  <img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/art_examples.png" width="720" />
@@ -212,6 +231,38 @@ const result = await qrCode.share({ name: "wifi", extension: "png", title: "Wi-F
212
231
  // "shared", "cancelled" or "downloaded"
213
232
  ```
214
233
 
234
+ ### Plugins
235
+
236
+ A plugin is a plain object with two optional hooks. `configure(options)` returns option changes to merge in before
237
+ drawing. `afterDraw(draw)` draws on top of the finished code, with the canvas context or the SVG element. It gets
238
+ the code's area in pixels (`x`, `y`, `size`, `dotSize`, `count`), and that area accounts for frames.
239
+
240
+ ```js
241
+ const ring = {
242
+ name: "ring",
243
+ configure: (options) => (options.margin < 24 ? { margin: 24 } : undefined),
244
+ afterDraw: ({ type, area, context, svg, document }) => {
245
+ const cx = area.x + area.size / 2, cy = area.y + area.size / 2, r = area.size * 0.75;
246
+ if (type === "canvas") {
247
+ context.beginPath();
248
+ context.arc(cx, cy, r, 0, Math.PI * 2);
249
+ context.strokeStyle = "#e11d48";
250
+ context.stroke();
251
+ } else {
252
+ const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
253
+ Object.entries({ cx, cy, r, fill: "none", stroke: "#e11d48" }).forEach(([k, v]) => circle.setAttribute(k, v));
254
+ svg.appendChild(circle);
255
+ }
256
+ }
257
+ };
258
+
259
+ new QRCodeStyling({ data: "https://example.com", plugins: [ring] });
260
+ ```
261
+
262
+ Plugins run in order, and async `afterDraw` hooks are awaited. `configure` runs again on every `update()`, so it
263
+ should return the same changes for the same options. Check the result with `verify()` when a plugin draws near
264
+ the code.
265
+
215
266
  ### Checking that a code scans
216
267
 
217
268
  `verify()` renders the code and decodes it with a QR decoder you pass in, so the library itself stays dependency-free.
@@ -248,6 +299,8 @@ width |number |`300` |Size of canvas
248
299
  height |number |`300` |Size of canvas
249
300
  type |string (`'canvas' 'svg'`)|`canvas` |The type of the element that will be rendered
250
301
  shape |string (`'square' 'circle'`)|`'square'` |`'circle'` draws a round code with decorative dots around the real one
302
+ svgOptions |object `{ mergePaths }` | |SVG only: `mergePaths: true` draws all dots as one path (smaller files)
303
+ plugins |array | |Plugins with `configure` and `afterDraw` hooks, see [Plugins](#plugins)
251
304
  data |string | |The date will be encoded to the QR code
252
305
  image |string | |The image will be copied to the center of the QR code
253
306
  margin |number |`0` |Margin around canvas
@@ -292,7 +345,7 @@ Property|Type
292
345
  --------|------------------------------------------------------------------------------|-------------|-------------------
293
346
  color |string |`'#000'` |Color of QR dots
294
347
  gradient|object | |Gradient of QR dots
295
- type |string (`'rounded' 'dots' 'classy' 'classy-rounded' 'square' 'extra-rounded' 'diamond' 'small-square' 'vertical-lines' 'horizontal-lines' 'fluid'`)|`'square'` |Style of QR dots. With `diamond`, `small-square` and the lines, corners and alignment patterns stay solid unless you set a corner type. `fluid` joins neighbouring dots into soft strokes, with solid rounded corners
348
+ type |string (`'rounded' 'dots' 'classy' 'classy-rounded' 'square' 'extra-rounded' 'diamond' 'small-square' 'vertical-lines' 'horizontal-lines' 'fluid' 'wave' 'blob' 'circuit'`)|`'square'` |Style of QR dots. With `diamond`, `small-square` and the lines, corners and alignment patterns stay solid unless you set a corner type. With `fluid`, `wave`, `blob` and `circuit` they are solid and rounded
296
349
 
297
350
  `options.backgroundOptions` structure
298
351
 
@@ -18,6 +18,7 @@ export default class QRCanvas {
18
18
  clear(): void;
19
19
  _drawFramed(qr: QRCode): Promise<void>;
20
20
  drawQR(qr: QRCode): Promise<void>;
21
+ _drawCode(qr: QRCode): Promise<void>;
21
22
  drawBackground(): void;
22
23
  drawDots(filter?: FilterFunction): void;
23
24
  _drawArtRects(rects: ArtRect[]): void;
@@ -27,9 +27,12 @@ export default class QRSVG {
27
27
  _svgElement(name: string, attributes: Record<string, string | number>): SVGElement;
28
28
  _drawFramed(qr: QRCode): Promise<void>;
29
29
  drawQR(qr: QRCode): Promise<void>;
30
+ _drawCode(qr: QRCode): Promise<void>;
30
31
  drawBackground(): void;
31
32
  drawDots(filter?: FilterFunction): void;
32
33
  drawCorners(): void;
34
+ /** Finder modules drawn with the dots' own figure, as one path (svgOptions.mergePaths). */
35
+ _drawMergedMask(mask: number[][], x: number, y: number, dotSize: number, clipPath?: SVGElement): void;
33
36
  _drawArtRects(rects: ArtRect[]): void;
34
37
  _appendImage(href: string, x: number, y: number): void;
35
38
  imageToBlob(): void;
@@ -48,3 +48,22 @@ export declare const fluid: (x: number, y: number, size: number, neighbors: {
48
48
  top: boolean;
49
49
  bottom: boolean;
50
50
  }) => Shape;
51
+ type Neighbors = {
52
+ left: boolean;
53
+ right: boolean;
54
+ top: boolean;
55
+ bottom: boolean;
56
+ };
57
+ /**
58
+ * "wave" dot: modules in a row flow into each other as a chain of soft beads; a run's ends are round.
59
+ * Only horizontal neighbours connect.
60
+ */
61
+ export declare const wave: (x: number, y: number, size: number, { left, right }: Neighbors) => Shape;
62
+ /** "blob" dot: a hand-drawn looking rounded square; each module gets its own corner radii and size. */
63
+ export declare const blob: (x: number, y: number, size: number) => Shape;
64
+ /**
65
+ * "circuit" dot: a round pad with thin traces to its dark neighbours, like a printed circuit board.
66
+ * One outline per module, so traces never overlap the pad (the renderers fill with even-odd).
67
+ */
68
+ export declare const circuit: (x: number, y: number, size: number, neighbors: Neighbors) => Shape;
69
+ export {};