qr-code-styling-node 1.10.0 → 1.11.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
@@ -169,6 +169,49 @@ placement |object `{ x, y, size }` | |Put the code in this
169
169
  Always check art codes with `verify()` below: a picture with large mid-grey areas or very small modules
170
170
  (under about 7 px) may need a higher `contrast`, a larger size or a higher error correction level.
171
171
 
172
+ ### Round QR codes
173
+
174
+ <img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/circle_examples.png" width="720" />
175
+
176
+ `shape: "circle"` draws a round code. The real code stays square in the middle, with an empty ring around it so
177
+ scanners still find it, and the rest of the circle is filled with decorative dots in the same style. The background
178
+ becomes a circle too. The decoration is the same every time for the same data.
179
+
180
+ ```js
181
+ new QRCodeStyling({ data: "https://example.com", shape: "circle", dotsOptions: { type: "rounded" } });
182
+ ```
183
+
184
+ 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
185
+ check it with `verify()`.
186
+
187
+ ### Wi-Fi, contacts, events and more
188
+
189
+ `QRCodeStyling.payload` (also exported as `payload`) builds the text that phones understand. Pass the result as `data`.
190
+
191
+ ```js
192
+ const { payload } = QRCodeStyling;
193
+
194
+ payload.wifi({ ssid: "LongChau-Guest", password: "secret" }); // WIFI:T:WPA;S:LongChau-Guest;P:secret;;
195
+ payload.vCard({ firstName: "Quân", lastName: "Nguyễn", phone: "+84900000000", email: "a@example.com" });
196
+ payload.event({ title: "Khai trương", start: "2026-12-01T09:00:00+07:00", end: "2026-12-01T11:00:00+07:00" });
197
+ payload.email({ to: "cskh@example.com", subject: "Hỏi đáp" });
198
+ payload.phone("1800 6928");
199
+ payload.sms({ number: "+84900000000", message: "Xin chào" });
200
+ payload.geo({ latitude: 10.7769, longitude: 106.7009 });
201
+ ```
202
+
203
+ Special characters are escaped for each format. Text outside Latin-1 (Vietnamese, emoji...) is encoded as UTF-8.
204
+
205
+ ### Sharing on phones
206
+
207
+ `share()` opens the phone's share sheet with the code as an image (Web Share API), so people can send it to a chat
208
+ app or save it to Photos. Where sharing files is not supported, it downloads the file instead.
209
+
210
+ ```js
211
+ const result = await qrCode.share({ name: "wifi", extension: "png", title: "Wi-Fi Long Châu" });
212
+ // "shared", "cancelled" or "downloaded"
213
+ ```
214
+
172
215
  ### Checking that a code scans
173
216
 
174
217
  `verify()` renders the code and decodes it with a QR decoder you pass in, so the library itself stays dependency-free.
@@ -204,6 +247,7 @@ Property |Type |Default Value|Description
204
247
  width |number |`300` |Size of canvas
205
248
  height |number |`300` |Size of canvas
206
249
  type |string (`'canvas' 'svg'`)|`canvas` |The type of the element that will be rendered
250
+ shape |string (`'square' 'circle'`)|`'square'` |`'circle'` draws a round code with decorative dots around the real one
207
251
  data |string | |The date will be encoded to the QR code
208
252
  image |string | |The image will be copied to the center of the QR code
209
253
  margin |number |`0` |Margin around canvas
@@ -324,6 +368,15 @@ Param |Type |Description
324
368
  decoder|function|A QR decoder with the jsQR signature `(rgba, width, height) => { data } \| null`
325
369
  adjust |boolean |For QR art: raise `art.contrast` until the code scans. Default `false`
326
370
 
371
+ `QRCodeStyling.share({ name, extension, title, text }) => Promise<'shared' | 'cancelled' | 'downloaded'>`
372
+
373
+ Param |Type |Default Value|Description
374
+ ---------|------------------------------------|-------------|------------
375
+ name |string |`'qr'` |File name, without extension
376
+ extension|string (`'png' 'jpeg' 'webp' 'svg'`)|`'png'` |File type
377
+ title |string | |Title for the share sheet
378
+ text |string | |Text for the share sheet
379
+
327
380
  `QRCodeStyling.update(options) => void`
328
381
 
329
382
  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
  }
@@ -41,8 +41,10 @@ export default class QRSVG {
41
41
  count: number;
42
42
  dotSize: number;
43
43
  }): void;
44
- _createColor({ options, color, additionalRotation, x, y, height, width, name, imageHref }: {
44
+ _createColor({ options, color, additionalRotation, x, y, height, width, name, imageHref, radius }: {
45
45
  imageHref?: string;
46
+ /** Rounds the rect's corners (a circle when it is half the size). */
47
+ radius?: number;
46
48
  options?: Gradient;
47
49
  color?: string;
48
50
  additionalRotation: number;
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;