@molecule/app-qr-code-react 3.0.0 → 4.0.1

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
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-10-27T23:36:35.744Z
6
+ Generated: 2026-11-21T12:47:02.521Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-qr-code-react
@@ -67,7 +67,13 @@ interface QrCodeLogo {
67
67
  * use `errorCorrection='H'` when overlaying a logo.
68
68
  */
69
69
  size?: number
70
- /** Alt text for the logo image (decorative if omitted). */
70
+ /**
71
+ * Accessible description of the QR code. The logo image itself is
72
+ * decorative (`<image>` sits inside the `role="img"` SVG, whose children are
73
+ * presentational, so its own label would never be read): when this is set,
74
+ * the text becomes the SVG's `<desc>`, named by the SVG's
75
+ * `aria-describedby`. Omit it for a purely decorative logo.
76
+ */
71
77
  alt?: string
72
78
  }
73
79
  ```
@@ -84,9 +90,16 @@ interface QrCodeProps {
84
90
  size?: number
85
91
  /** Error-correction level. Defaults to `'M'`. Use `'H'` if overlaying a logo. */
86
92
  errorCorrection?: QrErrorCorrectionLevel
87
- /** Foreground (dark module) color. Defaults to `'#000'`. */
93
+ /**
94
+ * Foreground (dark module) color. Defaults to `'#000'`. Data, not theme: a QR
95
+ * code must be dark modules on a light background whatever the theme, because
96
+ * scanners need that contrast.
97
+ */
88
98
  fgColor?: string
89
- /** Background color. Defaults to `'#fff'`. */
99
+ /**
100
+ * Background color. Defaults to `'#fff'`. Data, for the same reason as
101
+ * {@link QrCodeProps.fgColor}.
102
+ */
90
103
  bgColor?: string
91
104
  /** Quiet-zone margin in modules. Defaults to 2. */
92
105
  margin?: number
@@ -142,7 +155,10 @@ overlays a small center logo.
142
155
  Styling routes through `@molecule/app-ui`'s `getClassMap()` for the
143
156
  container; the only inline color attributes are the SVG `fill`s on the
144
157
  background rect and the dark-modules path (real SVG attributes — not
145
- Tailwind classes). Translations come from `@molecule/app-locales-qr-code`.
158
+ Tailwind classes). Those two colours are data, not theme: a QR code must be
159
+ dark modules on a light background whatever the theme (scanners need the
160
+ contrast), so `fgColor`/`bgColor` keep their literal black-and-white
161
+ defaults. Translations come from `@molecule/app-locales-qr-code`.
146
162
 
147
163
  Used by coupon-deals-platform (redemption codes), restaurant-ordering
148
164
  (table tokens), event-ticketing (tickets), voting-polling (ballot links).
@@ -171,7 +187,7 @@ function QrCode({
171
187
 
172
188
  Peer dependencies:
173
189
 
174
- - `@molecule/app-react` ^3.0.0
190
+ - `@molecule/app-react` ^4.0.0
175
191
  - `@molecule/app-ui` ^1.0.1
176
192
  - `react` ^18.0.0 || ^19.0.0
177
193
 
package/dist/QrCode.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { JSX } from 'react';
1
+ import { type JSX } from 'react';
2
2
  /** QR error-correction level. `L` ≈ 7%, `M` ≈ 15%, `Q` ≈ 25%, `H` ≈ 30%. */
3
3
  export type QrErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H';
4
4
  /** Optional center-logo overlay descriptor. */
@@ -11,7 +11,13 @@ export interface QrCodeLogo {
11
11
  * use `errorCorrection='H'` when overlaying a logo.
12
12
  */
13
13
  size?: number;
14
- /** Alt text for the logo image (decorative if omitted). */
14
+ /**
15
+ * Accessible description of the QR code. The logo image itself is
16
+ * decorative (`<image>` sits inside the `role="img"` SVG, whose children are
17
+ * presentational, so its own label would never be read): when this is set,
18
+ * the text becomes the SVG's `<desc>`, named by the SVG's
19
+ * `aria-describedby`. Omit it for a purely decorative logo.
20
+ */
15
21
  alt?: string;
16
22
  }
17
23
  /** QrCode component props. */
@@ -22,9 +28,16 @@ export interface QrCodeProps {
22
28
  size?: number;
23
29
  /** Error-correction level. Defaults to `'M'`. Use `'H'` if overlaying a logo. */
24
30
  errorCorrection?: QrErrorCorrectionLevel;
25
- /** Foreground (dark module) color. Defaults to `'#000'`. */
31
+ /**
32
+ * Foreground (dark module) color. Defaults to `'#000'`. Data, not theme: a QR
33
+ * code must be dark modules on a light background whatever the theme, because
34
+ * scanners need that contrast.
35
+ */
26
36
  fgColor?: string;
27
- /** Background color. Defaults to `'#fff'`. */
37
+ /**
38
+ * Background color. Defaults to `'#fff'`. Data, for the same reason as
39
+ * {@link QrCodeProps.fgColor}.
40
+ */
28
41
  bgColor?: string;
29
42
  /** Quiet-zone margin in modules. Defaults to 2. */
30
43
  margin?: number;
@@ -60,7 +73,10 @@ export declare function buildQrPath(qr: {
60
73
  * Styling routes through `@molecule/app-ui`'s `getClassMap()` for the
61
74
  * container; the only inline color attributes are the SVG `fill`s on the
62
75
  * background rect and the dark-modules path (real SVG attributes — not
63
- * Tailwind classes). Translations come from `@molecule/app-locales-qr-code`.
76
+ * Tailwind classes). Those two colours are data, not theme: a QR code must be
77
+ * dark modules on a light background whatever the theme (scanners need the
78
+ * contrast), so `fgColor`/`bgColor` keep their literal black-and-white
79
+ * defaults. Translations come from `@molecule/app-locales-qr-code`.
64
80
  *
65
81
  * Used by coupon-deals-platform (redemption codes), restaurant-ordering
66
82
  * (table tokens), event-ticketing (tickets), voting-polling (ballot links).
@@ -1 +1 @@
1
- {"version":3,"file":"QrCode.d.ts","sourceRoot":"","sources":["../src/QrCode.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAKhC,4EAA4E;AAC5E,MAAM,MAAM,sBAAsB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;AAE1D,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAA;IACX;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,eAAe,CAAC,EAAE,sBAAsB,CAAA;IACxC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE;IAAE,cAAc,EAAE,MAAM,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,EACnF,MAAM,EAAE,MAAM,GACb,MAAM,CAiBR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,EACrB,KAAK,EACL,IAAU,EACV,eAAqB,EACrB,OAAgB,EAChB,OAAgB,EAChB,MAAU,EACV,IAAI,EACJ,SAAS,EACT,SAAS,GACV,EAAE,WAAW,GAAG,GAAG,CAAC,OAAO,CAuD3B"}
1
+ {"version":3,"file":"QrCode.d.ts","sourceRoot":"","sources":["../src/QrCode.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,GAAG,EAAS,MAAM,OAAO,CAAA;AAKvC,4EAA4E;AAC5E,MAAM,MAAM,sBAAsB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;AAE1D,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAA;IACX;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,eAAe,CAAC,EAAE,sBAAsB,CAAA;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE;IAAE,cAAc,EAAE,MAAM,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,EACnF,MAAM,EAAE,MAAM,GACb,MAAM,CAiBR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,EACrB,KAAK,EACL,IAAU,EACV,eAAqB,EACrB,OAAgB,EAChB,OAAgB,EAChB,MAAU,EACV,IAAI,EACJ,SAAS,EACT,SAAS,GACV,EAAE,WAAW,GAAG,GAAG,CAAC,OAAO,CAkE3B"}
package/dist/QrCode.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import qrcode from 'qrcode-generator';
3
+ import { useId } from 'react';
3
4
  import { useTranslation } from '@molecule/app-react';
4
5
  import { getClassMap } from '@molecule/app-ui';
5
6
  /**
@@ -40,7 +41,10 @@ export function buildQrPath(qr, margin) {
40
41
  * Styling routes through `@molecule/app-ui`'s `getClassMap()` for the
41
42
  * container; the only inline color attributes are the SVG `fill`s on the
42
43
  * background rect and the dark-modules path (real SVG attributes — not
43
- * Tailwind classes). Translations come from `@molecule/app-locales-qr-code`.
44
+ * Tailwind classes). Those two colours are data, not theme: a QR code must be
45
+ * dark modules on a light background whatever the theme (scanners need the
46
+ * contrast), so `fgColor`/`bgColor` keep their literal black-and-white
47
+ * defaults. Translations come from `@molecule/app-locales-qr-code`.
44
48
  *
45
49
  * Used by coupon-deals-platform (redemption codes), restaurant-ordering
46
50
  * (table tokens), event-ticketing (tickets), voting-polling (ballot links).
@@ -51,6 +55,7 @@ export function buildQrPath(qr, margin) {
51
55
  export function QrCode({ value, size = 200, errorCorrection = 'M', fgColor = '#000', bgColor = '#fff', margin = 2, logo, ariaLabel, className, }) {
52
56
  const cm = getClassMap();
53
57
  const { t } = useTranslation();
58
+ const descId = useId();
54
59
  // typeNumber=0 lets the library pick the smallest type that fits.
55
60
  const qr = qrcode(0, errorCorrection);
56
61
  qr.addData(value);
@@ -63,5 +68,13 @@ export function QrCode({ value, size = 200, errorCorrection = 'M', fgColor = '#0
63
68
  // QR matrix regardless of `size`. Default to ~20% of the matrix.
64
69
  const logoModuleSize = logo?.size ? (logo.size / size) * totalModules : totalModules * 0.2;
65
70
  const logoOffset = (totalModules - logoModuleSize) / 2;
66
- return (_jsxs("svg", { width: size, height: size, viewBox: `0 0 ${totalModules} ${totalModules}`, role: "img", "aria-label": label, "data-mol-id": "qr-code", className: cm.cn(className), shapeRendering: "crispEdges", children: [_jsx("rect", { x: 0, y: 0, width: totalModules, height: totalModules, fill: bgColor, "data-mol-id": "qr-code-bg" }), _jsx("path", { d: pathData, fill: fgColor, "data-mol-id": "qr-code-modules" }), logo ? (_jsx("image", { href: logo.src, x: logoOffset, y: logoOffset, width: logoModuleSize, height: logoModuleSize, preserveAspectRatio: "xMidYMid meet", "data-mol-id": "qr-code-logo", "aria-label": logo.alt })) : null] }));
71
+ // The logo's alt text describes the whole code, not the overlay: an
72
+ // `<image>` inside the `role="img"` SVG is presentational, so its own
73
+ // `aria-label` would never reach the accessibility tree. It becomes the
74
+ // SVG's `<desc>` instead, named by `aria-describedby`.
75
+ const description = logo?.alt ? logo.alt : undefined;
76
+ // The module fills are data, not theme: a QR code must be dark modules on a
77
+ // light background whatever the theme, because scanners need the contrast.
78
+ // That is why `fgColor`/`bgColor` default to literal black and white.
79
+ return (_jsxs("svg", { width: size, height: size, viewBox: `0 0 ${totalModules} ${totalModules}`, role: "img", "aria-label": label, "aria-describedby": description ? descId : undefined, "data-mol-id": "qr-code", className: cm.cn(className), shapeRendering: "crispEdges", children: [description ? _jsx("desc", { id: descId, children: description }) : null, _jsx("rect", { x: 0, y: 0, width: totalModules, height: totalModules, fill: bgColor, "data-mol-id": "qr-code-bg" }), _jsx("path", { d: pathData, fill: fgColor, "data-mol-id": "qr-code-modules" }), logo ? (_jsx("image", { href: logo.src, x: logoOffset, y: logoOffset, width: logoModuleSize, height: logoModuleSize, preserveAspectRatio: "xMidYMid meet", "data-mol-id": "qr-code-logo" })) : null] }));
67
80
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-qr-code-react",
3
- "version": "3.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "Render a QR code as crisp scalable SVG with optional center logo",
5
5
  "homepage": "https://www.molecule.dev/packages/app-qr-code-react",
6
6
  "type": "module",
@@ -37,14 +37,14 @@
37
37
  "qrcode-generator": "2.0.4"
38
38
  },
39
39
  "peerDependencies": {
40
- "@molecule/app-react": "^3.0.0",
40
+ "@molecule/app-react": "^4.0.0",
41
41
  "@molecule/app-ui": "^1.0.1",
42
42
  "react": "^18.0.0 || ^19.0.0"
43
43
  },
44
44
  "devDependencies": {
45
- "@molecule/app-i18n": "1.1.1",
46
- "@molecule/app-react": "3.0.0",
47
- "@molecule/app-ui": "1.3.8",
45
+ "@molecule/app-i18n": "1.2.2",
46
+ "@molecule/app-react": "4.10.1",
47
+ "@molecule/app-ui": "1.5.0",
48
48
  "@testing-library/react": "16.3.3",
49
49
  "@types/node": "26.6.5",
50
50
  "@types/react": "19.3.0",