qr-code-styling-node 1.10.0 → 1.12.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" />
@@ -169,6 +188,49 @@ placement |object `{ x, y, size }` | |Put the code in this
169
188
  Always check art codes with `verify()` below: a picture with large mid-grey areas or very small modules
170
189
  (under about 7 px) may need a higher `contrast`, a larger size or a higher error correction level.
171
190
 
191
+ ### Round QR codes
192
+
193
+ <img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/circle_examples.png" width="720" />
194
+
195
+ `shape: "circle"` draws a round code. The real code stays square in the middle, with an empty ring around it so
196
+ scanners still find it, and the rest of the circle is filled with decorative dots in the same style. The background
197
+ becomes a circle too. The decoration is the same every time for the same data.
198
+
199
+ ```js
200
+ new QRCodeStyling({ data: "https://example.com", shape: "circle", dotsOptions: { type: "rounded" } });
201
+ ```
202
+
203
+ A round code uses smaller modules than a square one of the same size, so keep it at least ~240 px for short data and
204
+ check it with `verify()`.
205
+
206
+ ### Wi-Fi, contacts, events and more
207
+
208
+ `QRCodeStyling.payload` (also exported as `payload`) builds the text that phones understand. Pass the result as `data`.
209
+
210
+ ```js
211
+ const { payload } = QRCodeStyling;
212
+
213
+ payload.wifi({ ssid: "LongChau-Guest", password: "secret" }); // WIFI:T:WPA;S:LongChau-Guest;P:secret;;
214
+ payload.vCard({ firstName: "Quân", lastName: "Nguyễn", phone: "+84900000000", email: "a@example.com" });
215
+ payload.event({ title: "Khai trương", start: "2026-12-01T09:00:00+07:00", end: "2026-12-01T11:00:00+07:00" });
216
+ payload.email({ to: "cskh@example.com", subject: "Hỏi đáp" });
217
+ payload.phone("1800 6928");
218
+ payload.sms({ number: "+84900000000", message: "Xin chào" });
219
+ payload.geo({ latitude: 10.7769, longitude: 106.7009 });
220
+ ```
221
+
222
+ Special characters are escaped for each format. Text outside Latin-1 (Vietnamese, emoji...) is encoded as UTF-8.
223
+
224
+ ### Sharing on phones
225
+
226
+ `share()` opens the phone's share sheet with the code as an image (Web Share API), so people can send it to a chat
227
+ app or save it to Photos. Where sharing files is not supported, it downloads the file instead.
228
+
229
+ ```js
230
+ const result = await qrCode.share({ name: "wifi", extension: "png", title: "Wi-Fi Long Châu" });
231
+ // "shared", "cancelled" or "downloaded"
232
+ ```
233
+
172
234
  ### Checking that a code scans
173
235
 
174
236
  `verify()` renders the code and decodes it with a QR decoder you pass in, so the library itself stays dependency-free.
@@ -204,6 +266,8 @@ Property |Type |Default Value|Description
204
266
  width |number |`300` |Size of canvas
205
267
  height |number |`300` |Size of canvas
206
268
  type |string (`'canvas' 'svg'`)|`canvas` |The type of the element that will be rendered
269
+ shape |string (`'square' 'circle'`)|`'square'` |`'circle'` draws a round code with decorative dots around the real one
270
+ svgOptions |object `{ mergePaths }` | |SVG only: `mergePaths: true` draws all dots as one path (smaller files)
207
271
  data |string | |The date will be encoded to the QR code
208
272
  image |string | |The image will be copied to the center of the QR code
209
273
  margin |number |`0` |Margin around canvas
@@ -248,7 +312,7 @@ Property|Type
248
312
  --------|------------------------------------------------------------------------------|-------------|-------------------
249
313
  color |string |`'#000'` |Color of QR dots
250
314
  gradient|object | |Gradient of QR dots
251
- 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
315
+ 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
252
316
 
253
317
  `options.backgroundOptions` structure
254
318
 
@@ -324,6 +388,15 @@ Param |Type |Description
324
388
  decoder|function|A QR decoder with the jsQR signature `(rgba, width, height) => { data } \| null`
325
389
  adjust |boolean |For QR art: raise `art.contrast` until the code scans. Default `false`
326
390
 
391
+ `QRCodeStyling.share({ name, extension, title, text }) => Promise<'shared' | 'cancelled' | 'downloaded'>`
392
+
393
+ Param |Type |Default Value|Description
394
+ ---------|------------------------------------|-------------|------------
395
+ name |string |`'qr'` |File name, without extension
396
+ extension|string (`'png' 'jpeg' 'webp' 'svg'`)|`'png'` |File type
397
+ title |string | |Title for the share sheet
398
+ text |string | |Text for the share sheet
399
+
327
400
  `QRCodeStyling.update(options) => void`
328
401
 
329
402
  Param |Type |Description
@@ -1,8 +1,24 @@
1
1
  import QRCanvas from "./QRCanvas";
2
2
  import QRSVG from "./QRSVG";
3
3
  import { RequiredOptions } from "./QROptions";
4
- import { Extension, QRCode, Options, DownloadOptions, VerifyOptions, VerifyResult } from "../types";
4
+ import { Extension, QRCode, Options, DownloadOptions, VerifyOptions, VerifyResult, ShareOptions } from "../types";
5
5
  export default class QRCodeStyling {
6
+ /** Builders for Wi-Fi, contact, event, e-mail, phone, SMS and location codes: pass the result as `data`. */
7
+ static payload: {
8
+ wifi: typeof import("../tools/payloads").wifi;
9
+ vCard: typeof import("../tools/payloads").vCard;
10
+ event: typeof import("../tools/payloads").event;
11
+ email: typeof import("../tools/payloads").email;
12
+ phone: (number: string) => string;
13
+ sms: ({ number, message }: {
14
+ number: string;
15
+ message?: string;
16
+ }) => string;
17
+ geo: ({ latitude, longitude }: {
18
+ latitude: number;
19
+ longitude: number;
20
+ }) => string;
21
+ };
6
22
  _options: RequiredOptions;
7
23
  _container?: HTMLElement;
8
24
  _canvas?: QRCanvas;
@@ -43,4 +59,10 @@ export default class QRCodeStyling {
43
59
  verify({ decoder, adjust }: VerifyOptions): Promise<VerifyResult>;
44
60
  getRawData(extension?: Extension): Promise<Blob | Buffer | null>;
45
61
  download(downloadOptions?: Partial<DownloadOptions> | string): Promise<void>;
62
+ /**
63
+ * Opens the phone's share sheet with the QR code as a file (Web Share API). Where sharing files is not
64
+ * supported (most desktop browsers), downloads it instead. Resolves to "shared", "downloaded", or
65
+ * "cancelled" when the user closes the share sheet.
66
+ */
67
+ share(shareOptions?: ShareOptions): Promise<"shared" | "downloaded" | "cancelled">;
46
68
  }
@@ -30,6 +30,8 @@ export default class QRSVG {
30
30
  drawBackground(): void;
31
31
  drawDots(filter?: FilterFunction): void;
32
32
  drawCorners(): void;
33
+ /** Finder modules drawn with the dots' own figure, as one path (svgOptions.mergePaths). */
34
+ _drawMergedMask(mask: number[][], x: number, y: number, dotSize: number, clipPath?: SVGElement): void;
33
35
  _drawArtRects(rects: ArtRect[]): void;
34
36
  _appendImage(href: string, x: number, y: number): void;
35
37
  imageToBlob(): void;
@@ -41,8 +43,10 @@ export default class QRSVG {
41
43
  count: number;
42
44
  dotSize: number;
43
45
  }): void;
44
- _createColor({ options, color, additionalRotation, x, y, height, width, name, imageHref }: {
46
+ _createColor({ options, color, additionalRotation, x, y, height, width, name, imageHref, radius }: {
45
47
  imageHref?: string;
48
+ /** Rounds the rect's corners (a circle when it is half the size). */
49
+ radius?: number;
46
50
  options?: Gradient;
47
51
  color?: string;
48
52
  additionalRotation: number;
@@ -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 {};
package/lib/index.d.ts CHANGED
@@ -7,6 +7,8 @@ import errorCorrectionPercents from "./constants/errorCorrectionPercents";
7
7
  import modes from "./constants/modes";
8
8
  import qrTypes from "./constants/qrTypes";
9
9
  import drawTypes from "./constants/drawTypes";
10
+ import payload from "./tools/payloads";
10
11
  export * from "./types";
11
- export { dotTypes, cornerDotTypes, cornerSquareTypes, errorCorrectionLevels, errorCorrectionPercents, modes, qrTypes, drawTypes };
12
+ export type { WifiOptions, VCardOptions, EventOptions } from "./tools/payloads";
13
+ export { dotTypes, cornerDotTypes, cornerSquareTypes, errorCorrectionLevels, errorCorrectionPercents, modes, qrTypes, drawTypes, payload };
12
14
  export default QRCodeStyling;