docs: border plugin

Author: HitkoDev

README.md

@@ -125,6 +125,48 @@ const buffer = await new Promise((resolve) => {
 await writeFile('qr.pdf', buffer)
 ```
 
+### Plugins
+
+Version `5.0.0` of the library introduces plugin support, enabling you to further customize the shape of dots and corners. Additionally, plugins can apply effects, such as adding borders, to enhance the final QR code output.
+
+<p float="left">
+<img style="display:inline-block" src="https://raw.githubusercontent.com/Liquid-JS/qr-code-styling/master/src/assets/border.png" width="240" />
+</p>
+
+#### Plugin development
+
+A simple plugin example to customize QR code dots:
+
+```ts
+import { svgPath, DrawArgs } from '@liquid-js/qr-code-styling/plugin-utils'
+
+const qrCode = new QRCodeStyling({
+    plugins: [
+        {
+            drawDot: (args: DrawArgs): SVGElement | undefined => {
+                const { size, x, y, document } = args
+
+                const element = document.createElementNS('http://www.w3.org/2000/svg', 'path')                
+                // Insert your own SVG path definition, or implement neighbour-aware logic through args.getNeighbor()
+                element.setAttribute(
+                    'd',
+                    svgPath`M ${x} ${y + (size - size) / 2}
+                  v ${size}
+                  h ${size / 2}
+                  a ${size / 2} ${size / 2} 0 0 0 0 ${-size}
+                  z`
+                )
+
+                return element
+            }
+        },
+    ]
+    // ...other options
+})
+```
+
+See [Border plugin](https://github.com/Liquid-JS/qr-code-styling/tree/master/src/plugins/border.js) for further reference.
+
 ### Kanji support
 
 For Kanji mode to work, import `stringToBytesFuncs` from `@liquid-js/qr-code-styling/kanji` and inclue it with config.

package.json

@@ -115,7 +115,9 @@
         "logo",
         "design",
         "node",
-        "nodejs"
+        "nodejs",
+        "plugin",
+        "plugins"
     ],
     "author": "HitkoDev <development@hitko.si>",
     "license": "MIT",

src/assets/border.png

@@ -566,7 +566,7 @@ export class QRSVG {
                 const draw = getQrCornerDotFigure(options.cornersDotOptions.type)
 
                 if (cornersDotMaskGroup) {
-                    cornersDotMaskGroup.appendChild(draw(squareArgs))
+                    cornersDotMaskGroup.appendChild(draw(dotArgs))
                 }
             } else {
                 const draw = getQrDotFigure(options.cornersDotOptions?.type || options.dotsOptions.type, options.plugins)

src/core/qr-svg.ts

@@ -4,7 +4,7 @@ export { FileExtension } from './tools/browser-utils.js'
 export { type RecursivePartial } from './types/helper.js'
 export { type CanvasOptions } from './utils/canvas-options.js'
 export { GradientType, type Gradient } from './utils/gradient.js'
-export { CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options } from './utils/options.js'
+export { CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options, type Plugin } from './utils/options.js'
 export { ErrorCorrectionPercents } from './utils/qrcode.js'
 import * as _browserUtils from './tools/browser-utils.js'
 

src/index.ts

@@ -11,7 +11,7 @@ export { FileExtension } from './tools/browser-utils.js'
 export { type RecursivePartial } from './types/helper.js'
 export { type CanvasOptions } from './utils/canvas-options.js'
 export { GradientType, type Gradient } from './utils/gradient.js'
-export { CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options } from './utils/options.js'
+export { CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options, type Plugin } from './utils/options.js'
 export { ErrorCorrectionPercents } from './utils/qrcode.js'
 
 export const browserUtils: typeof _browserUtils | undefined = undefined

src/node.ts

@@ -46,14 +46,14 @@ export class BorderPlugin implements Plugin {
             + (this.pluginOptions.innerBorder?.size || 0) + (this.pluginOptions.innerBorder?.margin || 0)
             + (this.pluginOptions.outerBorder?.size || 0) + (this.pluginOptions.outerBorder?.margin || 0)
         )
-        const vb = extendSVG(svg, thickness)
-        if (!vb)
+        const drawArea = extendSVG(svg, thickness)
+        if (!drawArea)
             return
 
-        const cx = (vb.left * 2 + vb.right) / 2
-        const cy = (vb.top * 2 + vb.bottom) / 2
+        const cx = (drawArea.left + drawArea.right) / 2
+        const cy = (drawArea.top + drawArea.bottom) / 2
         const lineSize = Math.min(options.width, options.height) / 2 * (1 - (this.pluginOptions.round || 0))
-        let r = (Math.min(vb.right - 2 * thickness, vb.bottom - 2 * thickness) / 2) - lineSize
+        let r = (Math.min(drawArea.right - drawArea.left - 2 * thickness, drawArea.bottom - drawArea.top - 2 * thickness) / 2) - lineSize
 
         const drawBorder = (cfg: BorderConfig) => {
             const t = cfg.size

src/plugins/border.ts

@@ -1 +1,2 @@
+export { type DrawArgs } from '../types/helper.js'
 export * from '../utils/svg.js'

src/plugins/utils.ts

@@ -63,8 +63,8 @@ export function extendSVG(svg: SVGSVGElement, padding: number) {
         return undefined
     return {
         left: vb[0],
-        right: vb[2],
+        right: vb[2] + vb[0],
         top: vb[1],
-        bottom: vb[3]
+        bottom: vb[3] + vb[1]
     }
 }

src/utils/svg.ts

@@ -3,7 +3,9 @@
     "entryPoints": [
         "./src/index.ts",
         "./src/tools/browser-utils.ts",
-        "./src/tools/browser-image-tools.ts"
+        "./src/tools/browser-image-tools.ts",
+        "./src/plugins/utils.ts",
+        "./src/plugins/border.ts"
     ],
     "out": "docs",
     "sort": [