qreator 9.8.2 → 9.9.0

package/README.md

@@ -4,7 +4,20 @@
 
 QR Code generator for browser and node.js with tree shaking and logo support
 
-![image](https://github.com/Short-io/qreator/assets/75169/02b84738-56f2-44d8-8d11-f40e263302ed)
+<table>
+<tr>
+<td align="center"><img src="showcase/classic.png" width="180" /><br /><b>Classic</b></td>
+<td align="center"><img src="showcase/rounded.png" width="180" /><br /><b>Rounded</b></td>
+<td align="center"><img src="showcase/drops.png" width="180" /><br /><b>Custom finders</b></td>
+<td align="center"><img src="showcase/logo.png" width="180" /><br /><b>Logo overlay</b></td>
+</tr>
+<tr>
+<td align="center"><img src="showcase/label-below.png" width="180" /><br /><b>Label: below</b></td>
+<td align="center"><img src="showcase/label-pill.png" width="180" /><br /><b>Label: pill</b></td>
+<td align="center"><img src="showcase/label-box.png" width="180" /><br /><b>Label: box</b></td>
+<td align="center"><img src="showcase/branded.png" width="180" /><br /><b>Branded</b></td>
+</tr>
+</table>
 
 ## Overview
 
@@ -16,6 +29,8 @@ QR Code generator for browser and node.js with tree shaking and logo support
 -   supports border-radius
 -   supports corner mode (merged rounded corners)
 -   supports finder pattern customization (shape + color)
+-   supports text labels (below, pill, box styles)
+-   optional React component
 -   tree shaking support
 -   browser / node.js
 
@@ -49,6 +64,15 @@ const pngBuffer = await getPNG("I love QR", {
 });
 ```
 
+### Label
+
+```javascript
+const png = await getPNG("https://example.com", {
+    labelText: "SCAN ME",
+    labelStyle: "pill", // "below", "pill", or "box"
+});
+```
+
 ### Finder pattern customization
 
 ```javascript
@@ -61,6 +85,16 @@ const svgString = await getSVG("I love QR", {
 });
 ```
 
+### React
+
+```jsx
+import { QR } from "qreator/lib/react";
+
+function App() {
+    return <QR text="https://example.com" labelText="SCAN ME" labelStyle="pill" />;
+}
+```
+
 [More examples](./examples)
 
 ### Syntax
@@ -94,6 +128,12 @@ const svgString = await getSVG("I love QR", {
 | `finderInnerShape` | shape of the inner dot of finder patterns      |   string    | `square`, `rounded`, `circle`, `drop` |          `undefined`           |
 | `finderColor`  | color of finder patterns (overrides `color`)       |   number/string   | same as `color` |              `undefined`                |
 | `noExcavate`   |        don't remove partially covered modules      |   boolean   |    `true`, `false`    |                 `false`                  |
+| `labelText`    |              text label to display below QR        |   string    |           -           |               `undefined`                |
+| `labelStyle`   |              label presentation style              |   string    | `below`, `pill`, `box` |                `below`                  |
+| `labelColor`   |              label text color                      |   number/string   | same as `color` |  `color` (below) / `bgColor` (pill/box)  |
+| `labelBgColor` |       label background color (pill/box only)       |   number/string   | same as `color` |              same as `color`              |
+| `labelFontSize`|       font size as multiple of module size         |   number    |        `1` - n        |                   `5`                    |
+| `labelFontFamily`|              font family                         |   string    |           -           |              `sans-serif`                |
 
 
 ## Benchmarks

package/lib/browser/pdf.umd.js

@@ -26828,6 +26828,12 @@
         const defaults = type === "png" ? BITMAP_OPTIONS : VECTOR_OPTIONS;
         return { ...defaults, ...inOptions };
     }
+    function colorToHex(color) {
+        if (typeof color === "string") {
+            return colorString.to.hex(colorString.get.rgb(color));
+        }
+        return `#${(color >>> 8).toString(16).padStart(6, "0")}`;
+    }
     const svgMove = (left, top) => ['M', left, top];
     const svgReturn = () => ['z'];
     const svgDeltaArc = (borderRadius, dx, dy, sweep = 0) => borderRadius > 0 ? ['a', borderRadius, borderRadius, 0, 0, sweep, dx, dy] : [];
@@ -26991,6 +26997,83 @@
         margin: 1,
         size: 0,
     };
+    function computeLabelLayout(options, qrSizePx, marginPx, moduleSize) {
+        if (!options.labelText)
+            return null;
+        const style = options.labelStyle ?? "below";
+        const fontSize = (options.labelFontSize ?? 5) * moduleSize;
+        const fontFamily = options.labelFontFamily ?? "sans-serif";
+        const fgColor = colorToHex(options.color ?? 0x000000ff);
+        const bgColorHex = colorToHex(options.bgColor ?? 0xffffffff);
+        const textColor = options.labelColor
+            ? colorToHex(options.labelColor)
+            : style === "below" ? fgColor : bgColorHex;
+        const labelBgColor = options.labelBgColor
+            ? colorToHex(options.labelBgColor)
+            : fgColor;
+        if (style === "below") {
+            const stripHeight = fontSize * 2.5;
+            return {
+                totalWidth: qrSizePx,
+                totalHeight: qrSizePx + stripHeight,
+                qrSize: qrSizePx,
+                label: {
+                    text: options.labelText,
+                    x: qrSizePx / 2,
+                    y: qrSizePx + stripHeight / 2,
+                    width: qrSizePx,
+                    height: stripHeight,
+                    fontSize,
+                    fontFamily,
+                    textColor,
+                    bgColor: null,
+                    borderRadius: 0,
+                },
+            };
+        }
+        if (style === "pill") {
+            const pillHeight = fontSize * 2.2;
+            const estimatedTextWidth = options.labelText.length * fontSize * 0.7;
+            const pillWidth = Math.min(Math.max(estimatedTextWidth + fontSize * 2, qrSizePx * 0.3), qrSizePx * 0.95);
+            const stripHeight = pillHeight + fontSize * 0.6;
+            return {
+                totalWidth: qrSizePx,
+                totalHeight: qrSizePx + stripHeight,
+                qrSize: qrSizePx,
+                label: {
+                    text: options.labelText,
+                    x: qrSizePx / 2,
+                    y: qrSizePx + stripHeight / 2,
+                    width: pillWidth,
+                    height: pillHeight,
+                    fontSize,
+                    fontFamily,
+                    textColor,
+                    bgColor: labelBgColor,
+                    borderRadius: pillHeight / 2,
+                },
+            };
+        }
+        const boxHeight = fontSize * 2.2;
+        const stripHeight = boxHeight + fontSize * 0.4;
+        return {
+            totalWidth: qrSizePx,
+            totalHeight: qrSizePx + stripHeight,
+            qrSize: qrSizePx,
+            label: {
+                text: options.labelText,
+                x: qrSizePx / 2,
+                y: qrSizePx + stripHeight / 2,
+                width: qrSizePx,
+                height: boxHeight,
+                fontSize,
+                fontFamily,
+                textColor,
+                bgColor: labelBgColor,
+                borderRadius: 0,
+            },
+        };
+    }
 
     function zeroFillFinders(matrix) {
         matrix = structuredClone(matrix);
@@ -27038,7 +27121,11 @@
         if (options.logo && options.logoWidth && options.logoHeight && !options.noExcavate) {
             matrix = clearMatrixCenter(matrix, options.logoWidth, options.logoHeight);
         }
-        return PDF({ matrix, ...options });
+        const pdfSize = 9;
+        const marginPx = options.margin * pdfSize;
+        const imageSizePx = matrix.length * pdfSize + 2 * marginPx;
+        const layout = computeLabelLayout(options, imageSizePx, marginPx, pdfSize);
+        return PDF({ matrix, ...options, labelLayout: layout });
     }
     function colorToRGB(color) {
         if (typeof color === "string") {
@@ -27079,15 +27166,20 @@
         page.getContentStream = page.prevGetContentStream;
         page.contentStream.push = page.contentStream.prevPush;
     }
-    async function PDF({ matrix, margin, logo, logoWidth, logoHeight, color, bgColor, borderRadius, cornerMode, finderOuterShape, finderInnerShape, finderColor, }) {
+    async function PDF({ matrix, margin, logo, logoWidth, logoHeight, color, bgColor, borderRadius, cornerMode, finderOuterShape, finderInnerShape, finderColor, labelLayout, }) {
         const size = 9;
         const marginPx = margin * size;
         const matrixSizePx = matrix.length * size;
         const imageSizePx = matrixSizePx + 2 * marginPx;
+        const totalWidth = labelLayout?.totalWidth ?? imageSizePx;
+        const totalHeight = labelLayout?.totalHeight ?? imageSizePx;
         const document = await PDFDocument.create();
-        const page = document.addPage([imageSizePx, imageSizePx]);
-        page.drawSquare({
-            size: imageSizePx,
+        const page = document.addPage([totalWidth, totalHeight]);
+        page.drawRectangle({
+            x: 0,
+            y: 0,
+            width: totalWidth,
+            height: totalHeight,
             color: rgb(...colorToRGB(bgColor)),
         });
         page.moveTo(0, page.getHeight());
@@ -27133,8 +27225,50 @@
                 height: logoHeightPx,
             });
         }
+        if (labelLayout) {
+            await drawPDFLabel(document, page, labelLayout, totalHeight);
+        }
         return document.save();
     }
+    async function drawPDFLabel(document, page, layout, totalHeight) {
+        const { label } = layout;
+        const font = await document.embedFont(StandardFonts.Helvetica);
+        const pdfLabelCenterY = totalHeight - label.y;
+        if (label.bgColor) {
+            const [r, g, b] = colorToRGB(label.bgColor);
+            const rectX = label.x - label.width / 2;
+            const rectY = pdfLabelCenterY - label.height / 2;
+            if (label.borderRadius > 0) {
+                const w = label.width;
+                const h = label.height;
+                const rad = Math.min(label.borderRadius, w / 2, h / 2);
+                const pillPath = `M ${rectX + rad} 0 h ${w - 2 * rad} a ${rad} ${rad} 0 0 1 ${rad} ${-rad} v ${-(h - 2 * rad)} a ${rad} ${rad} 0 0 1 ${-rad} ${-rad} h ${-(w - 2 * rad)} a ${rad} ${rad} 0 0 1 ${-rad} ${rad} v ${h - 2 * rad} a ${rad} ${rad} 0 0 1 ${rad} ${rad} z`;
+                page.moveTo(0, rectY + label.height);
+                page.drawSvgPath(pillPath, {
+                    color: rgb(r, g, b),
+                });
+                page.moveTo(0, page.getHeight());
+            }
+            else {
+                page.drawRectangle({
+                    x: rectX,
+                    y: rectY,
+                    width: label.width,
+                    height: label.height,
+                    color: rgb(r, g, b),
+                });
+            }
+        }
+        const textWidth = font.widthOfTextAtSize(label.text, label.fontSize);
+        const [tr, tg, tb] = colorToRGB(label.textColor);
+        page.drawText(label.text, {
+            x: label.x - textWidth / 2,
+            y: pdfLabelCenterY - label.fontSize * 0.35,
+            size: label.fontSize,
+            font,
+            color: rgb(tr, tg, tb),
+        });
+    }
 
     exports.getPDF = getPDF;