@particle-academy/react-fancy 6.7.2 → 6.8.0

package/CHANGELOG.md

@@ -11,7 +11,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [6.7.2] - 2026-11-08
+## [6.8.0] - 2026-11-04
+
+### Added
+
+- **`QrCodePanel`: download, share and print a QR code.** It composes `<QrCode>` with four actions, each a react-fancy `Button`: download as SVG, download as PNG, share (the Web Share sheet, or a copy of the value where there is none; the button then reads "Copy link" or "Copy"), and print (a frame holding only the code, plus the value when shown). `showValue` puts the value on screen as selectable text, off by default because a value can be a password. The code tile is black on white in dark mode too, because a QR code needs a light surround to scan; that is 21:1, past WCAG AAA. Buttons default to `lg`, 44px tall, WCAG 2.5.5's AAA target size. Every action reports through `onAction` as plain JSON (`{ action, outcome, via?, fileName?, error? }`, `outcome` one of `"done"`, `"cancelled"`, `"failed"`), what each did is announced in a polite `role="status"`, and every part has a `data-react-fancy-qr-code-*` handle. In the `./qr-code` subpath. **Consumer action:** none. `<QrCode>` is unchanged.
+- **`qrCodeSvg(value, options)` and `qrCodePng(value, options)`**, the panel's file formats as plain functions. The SVG is a standalone document with a `<title>` and an accessible name. The PNG is drawn with `Path2D` from the same path data, at a whole number of pixels per module (at most 8192 pixels a side), rather than by loading the SVG into an image, which a CSP of `img-src 'self'` would block. Files are always opaque: `transparent` becomes white and `currentColor` black, since a file has no page behind it. The label is escaped, and characters XML cannot carry (C0 controls other than tab, newline and return; lone surrogates) are dropped or replaced, so a hostile label still gives a valid file. **Consumer action:** none.
+
+### Changed
+
+- **`<QrCode>` draws its path with the same builder as the file exports**, so a downloaded file carries exactly the modules on screen. The output is unchanged, byte for byte. **Consumer action:** none.
+
+## [6.7.2] - 2026-11-04
 
 ### Fixed
 

package/dist/{chunk-AE53RKWR.cjs → chunk-CNWTYRZC.cjs}

@@ -1,5 +1,6 @@
 'use strict';
 
+var chunkNZHVDWOM_cjs = require('./chunk-NZHVDWOM.cjs');
 var chunkZU5Q77OT_cjs = require('./chunk-ZU5Q77OT.cjs');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
@@ -596,6 +597,29 @@ function encodeQr(value, options = {}) {
     mask: best.mask
   };
 }
+
+// src/components/QrCode/qr-path.ts
+function modulePath(modules, quietZone) {
+  const size = modules.length;
+  const parts = [];
+  for (let row = 0; row < size; row += 1) {
+    const line = modules[row];
+    let col = 0;
+    while (col < size) {
+      if (!line[col]) {
+        col += 1;
+        continue;
+      }
+      let run = 1;
+      while (col + run < size && line[col + run]) {
+        run += 1;
+      }
+      parts.push(`M${col + quietZone} ${row + quietZone}h${run}v1h-${run}z`);
+      col += run;
+    }
+  }
+  return parts.join("");
+}
 var QrCode = react.forwardRef(
   ({
     value,
@@ -615,26 +639,7 @@ var QrCode = react.forwardRef(
       [value, errorCorrection, mode, version]
     );
     const extent = symbol.size + quietZone * 2;
-    const path = react.useMemo(() => {
-      const parts = [];
-      for (let row = 0; row < symbol.size; row += 1) {
-        const line = symbol.modules[row];
-        let col = 0;
-        while (col < symbol.size) {
-          if (!line[col]) {
-            col += 1;
-            continue;
-          }
-          let run = 1;
-          while (col + run < symbol.size && line[col + run]) {
-            run += 1;
-          }
-          parts.push(`M${col + quietZone} ${row + quietZone}h${run}v1h-${run}z`);
-          col += run;
-        }
-      }
-      return parts.join("");
-    }, [symbol, quietZone]);
+    const path = react.useMemo(() => modulePath(symbol.modules, quietZone), [symbol, quietZone]);
     return /* @__PURE__ */ jsxRuntime.jsxs(
       "svg",
       {
@@ -657,8 +662,388 @@ var QrCode = react.forwardRef(
 );
 QrCode.displayName = "QrCode";
 
+// src/components/QrCode/qr-export.ts
+var DEFAULT_PIXELS_PER_MODULE = 10;
+var MAX_PNG_SIDE = 8192;
+var WHITE = "#ffffff";
+var BLACK = "#000000";
+function fileBackground(colour) {
+  return colour === void 0 || colour === "" || colour === "transparent" || colour === "none" ? WHITE : colour;
+}
+function fileForeground(colour) {
+  return colour === void 0 || colour === "" || colour === "currentColor" ? BLACK : colour;
+}
+var REPLACEMENT = String.fromCharCode(65533);
+function xmlChars(text) {
+  let out = "";
+  for (const char of text) {
+    const code = char.charCodeAt(0);
+    if (code < 32 && code !== 9 && code !== 10 && code !== 13) {
+      continue;
+    }
+    out += char.length === 1 && code >= 55296 && code <= 57343 ? REPLACEMENT : char;
+  }
+  return out;
+}
+function xml(text) {
+  return xmlChars(text).replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      default:
+        return "&#39;";
+    }
+  });
+}
+function symbolFor(value, options) {
+  const symbol = encodeQr(value, {
+    errorCorrection: options.errorCorrection,
+    mode: options.mode,
+    version: options.version
+  });
+  const quietZone = Math.max(0, Math.floor(options.quietZone ?? 4));
+  return { symbol, quietZone, extent: symbol.size + quietZone * 2 };
+}
+function qrCodeSvg(value, options) {
+  const { symbol, quietZone, extent } = symbolFor(value, options);
+  const size = options.size !== void 0 && Number.isFinite(options.size) && options.size > 0 ? options.size : extent * DEFAULT_PIXELS_PER_MODULE;
+  const label = xml(options.label);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${extent} ${extent}" shape-rendering="crispEdges" role="img" aria-label="${label}"><title>${label}</title><rect width="${extent}" height="${extent}" fill="${xml(fileBackground(options.background))}"/><path d="${modulePath(symbol.modules, quietZone)}" fill="${xml(fileForeground(options.foreground))}"/></svg>
+`;
+}
+function pngScale(scale, extent) {
+  const wanted = scale === void 0 || Number.isNaN(scale) ? DEFAULT_PIXELS_PER_MODULE : Math.floor(scale);
+  const ceiling = Math.max(1, Math.floor(MAX_PNG_SIDE / extent));
+  return Math.min(Math.max(1, wanted), ceiling);
+}
+function qrCodePng(value, options) {
+  const { symbol, quietZone, extent } = symbolFor(value, options);
+  const scale = pngScale(options.scale, extent);
+  const canvas = options.canvas ?? document.createElement("canvas");
+  canvas.width = extent * scale;
+  canvas.height = extent * scale;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) {
+    return Promise.reject(new Error("Canvas 2D is unavailable, so no PNG can be drawn"));
+  }
+  ctx.imageSmoothingEnabled = false;
+  ctx.fillStyle = WHITE;
+  ctx.fillStyle = fileBackground(options.background);
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  ctx.setTransform(scale, 0, 0, scale, 0, 0);
+  ctx.fillStyle = BLACK;
+  ctx.fillStyle = fileForeground(options.foreground);
+  ctx.fill(new Path2D(modulePath(symbol.modules, quietZone)));
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (blob) {
+        resolve(blob);
+      } else {
+        reject(new Error("The browser produced no PNG for this canvas"));
+      }
+    }, "image/png");
+  });
+}
+function safeFileName(name, fallback) {
+  const replaced = name.slice(0, 1e3).replace(/[^A-Za-z0-9._-]+/g, "-");
+  let start = 0;
+  let end = replaced.length;
+  while (start < end && (replaced[start] === "." || replaced[start] === "-")) {
+    start += 1;
+  }
+  while (end > start && (replaced[end - 1] === "." || replaced[end - 1] === "-")) {
+    end -= 1;
+  }
+  const trimmed = replaced.slice(start, Math.min(end, start + 100));
+  return trimmed === "" ? fallback : trimmed;
+}
+var DEFAULT_ACTIONS = ["download-svg", "download-png", "share", "print"];
+var DEFAULT_LABELS = {
+  downloadSvg: "Download SVG",
+  downloadPng: "Download PNG",
+  share: "Share",
+  copyLink: "Copy link",
+  copy: "Copy",
+  print: "Print",
+  downloaded: "Downloaded",
+  shared: "Shared",
+  copied: "Copied",
+  printing: "Opened the print dialog",
+  failed: "That did not work"
+};
+var ICONS = {
+  "download-svg": "download",
+  "download-png": "download",
+  share: "share-2",
+  print: "printer"
+};
+function isWebUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isAbort(error) {
+  return typeof error === "object" && error !== null && error.name === "AbortError";
+}
+function saveBlob(blob, fileName) {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = fileName;
+  anchor.rel = "noopener";
+  anchor.click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+var PRINT_FRAME = "data-react-fancy-qr-code-print";
+var QrCodePanel = react.forwardRef(
+  ({
+    value,
+    label,
+    size = 192,
+    errorCorrection = "M",
+    quietZone = 4,
+    foreground = "#000000",
+    background = "#ffffff",
+    mode,
+    version,
+    actions = DEFAULT_ACTIONS,
+    showValue = false,
+    fileName = "qr-code",
+    pngScale: pngScale2,
+    shareTitle,
+    printSizeMm = 50,
+    labels: labelOverrides,
+    onAction,
+    buttonSize = "lg",
+    className,
+    ...props
+  }, ref) => {
+    const labels = { ...DEFAULT_LABELS, ...labelOverrides };
+    const [status, setStatus] = react.useState("");
+    const [via, setVia] = react.useState("clipboard");
+    const frameRef = react.useRef(null);
+    react.useEffect(() => {
+      setVia(typeof navigator !== "undefined" && typeof navigator.share === "function" ? "share" : "clipboard");
+    }, []);
+    react.useEffect(
+      () => () => {
+        frameRef.current?.remove();
+        frameRef.current = null;
+      },
+      []
+    );
+    const file = { label, errorCorrection, mode, version, quietZone, foreground, background };
+    const base = safeFileName(fileName, "qr-code");
+    const link = isWebUrl(value);
+    const report = react.useCallback(
+      (event, announcement) => {
+        setStatus(announcement);
+        onAction?.(event);
+      },
+      [onAction]
+    );
+    const downloadSvg = () => {
+      const name = `${base}.svg`;
+      try {
+        saveBlob(new Blob([qrCodeSvg(value, file)], { type: "image/svg+xml" }), name);
+        report({ action: "download-svg", outcome: "done", fileName: name }, labels.downloaded);
+      } catch (error) {
+        report({ action: "download-svg", outcome: "failed", error: message(error) }, labels.failed);
+      }
+    };
+    const downloadPng = async () => {
+      const name = `${base}.png`;
+      try {
+        const blob = await qrCodePng(value, { ...file, scale: pngScale2 });
+        saveBlob(blob, name);
+        report({ action: "download-png", outcome: "done", fileName: name }, labels.downloaded);
+      } catch (error) {
+        report({ action: "download-png", outcome: "failed", error: message(error) }, labels.failed);
+      }
+    };
+    const copy = async () => {
+      try {
+        const clipboard = typeof navigator !== "undefined" ? navigator.clipboard : void 0;
+        if (!clipboard || typeof clipboard.writeText !== "function") {
+          throw new Error("The Clipboard API is unavailable");
+        }
+        await clipboard.writeText(value);
+        report({ action: "share", outcome: "done", via: "clipboard" }, labels.copied);
+      } catch (error) {
+        report({ action: "share", outcome: "failed", via: "clipboard", error: message(error) }, labels.failed);
+      }
+    };
+    const share = async () => {
+      const title = shareTitle ?? label;
+      const data = link ? { title, url: value } : { title, text: value };
+      const canShare = typeof navigator !== "undefined" && typeof navigator.share === "function" && (typeof navigator.canShare !== "function" || navigator.canShare(data));
+      if (!canShare) {
+        await copy();
+        return;
+      }
+      try {
+        await navigator.share(data);
+        report({ action: "share", outcome: "done", via: "share" }, labels.shared);
+      } catch (error) {
+        if (isAbort(error)) {
+          report({ action: "share", outcome: "cancelled", via: "share" }, "");
+          return;
+        }
+        await copy();
+      }
+    };
+    const print = () => {
+      frameRef.current?.remove();
+      document.querySelectorAll(`iframe[${PRINT_FRAME}]`).forEach((stale) => stale.remove());
+      const frame = document.createElement("iframe");
+      frame.setAttribute(PRINT_FRAME, "");
+      frame.setAttribute("aria-hidden", "true");
+      frame.tabIndex = -1;
+      Object.assign(frame.style, { position: "fixed", right: "0", bottom: "0", width: "0", height: "0", border: "0" });
+      document.body.appendChild(frame);
+      frameRef.current = frame;
+      const doc = frame.contentDocument;
+      const win = frame.contentWindow;
+      if (!doc || !win) {
+        report({ action: "print", outcome: "failed", error: "The print frame has no document" }, labels.failed);
+        return;
+      }
+      doc.title = label;
+      Object.assign(doc.body.style, {
+        margin: "0",
+        padding: "15mm 10mm",
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "6mm",
+        color: "#000000",
+        background: "#ffffff",
+        fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+      });
+      const parsed = new DOMParser().parseFromString(qrCodeSvg(value, file), "image/svg+xml");
+      const svg = doc.importNode(parsed.documentElement, true);
+      const millimetres = Number.isFinite(printSizeMm) && printSizeMm > 0 ? printSizeMm : 50;
+      svg.setAttribute("width", `${millimetres}mm`);
+      svg.setAttribute("height", `${millimetres}mm`);
+      doc.body.appendChild(svg);
+      if (showValue) {
+        const text2 = doc.createElement("p");
+        text2.textContent = value;
+        Object.assign(text2.style, {
+          margin: "0",
+          maxWidth: `${Math.max(millimetres, 80)}mm`,
+          fontSize: "12pt",
+          textAlign: "center",
+          overflowWrap: "anywhere"
+        });
+        doc.body.appendChild(text2);
+      }
+      win.addEventListener("afterprint", () => {
+        if (frameRef.current === frame) {
+          frameRef.current = null;
+        }
+        frame.remove();
+      });
+      setTimeout(() => {
+        try {
+          win.print();
+          report({ action: "print", outcome: "done" }, labels.printing);
+        } catch (error) {
+          report({ action: "print", outcome: "failed", error: message(error) }, labels.failed);
+        }
+      }, 0);
+    };
+    const run = {
+      "download-svg": downloadSvg,
+      "download-png": () => void downloadPng(),
+      share: () => void share(),
+      print
+    };
+    const text = {
+      "download-svg": labels.downloadSvg,
+      "download-png": labels.downloadPng,
+      share: via === "share" ? labels.share : link ? labels.copyLink : labels.copy,
+      print: labels.print
+    };
+    return /* @__PURE__ */ jsxRuntime.jsxs(
+      "div",
+      {
+        ref,
+        role: "group",
+        "aria-label": label,
+        "data-react-fancy-qr-code-panel": "",
+        className: chunkZU5Q77OT_cjs.cn("inline-flex max-w-full flex-col items-center gap-3", className),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsxRuntime.jsx("div", { "data-react-fancy-qr-code-panel-code": "", className: "leading-none", children: /* @__PURE__ */ jsxRuntime.jsx(
+            QrCode,
+            {
+              value,
+              label,
+              size,
+              errorCorrection,
+              quietZone,
+              foreground,
+              background,
+              mode,
+              version
+            }
+          ) }),
+          showValue && /* @__PURE__ */ jsxRuntime.jsx(
+            "p",
+            {
+              "data-react-fancy-qr-code-panel-value": "",
+              className: "m-0 max-w-full select-all break-all text-center font-mono text-sm text-zinc-900 dark:text-zinc-100",
+              children: value
+            }
+          ),
+          actions.length > 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { "data-react-fancy-qr-code-panel-actions": "", className: "flex flex-wrap justify-center gap-2", children: actions.map((action) => /* @__PURE__ */ jsxRuntime.jsx(
+            chunkNZHVDWOM_cjs.Button,
+            {
+              size: buttonSize,
+              icon: action === "share" && via === "clipboard" ? "copy" : ICONS[action],
+              "data-react-fancy-qr-code-action": action,
+              "data-via": action === "share" ? via : void 0,
+              onClick: run[action],
+              children: text[action]
+            },
+            action
+          )) }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "span",
+            {
+              role: "status",
+              "aria-live": "polite",
+              "data-react-fancy-qr-code-panel-status": "",
+              className: "sr-only",
+              children: status
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+QrCodePanel.displayName = "QrCodePanel";
+
 exports.QrCode = QrCode;
+exports.QrCodePanel = QrCodePanel;
 exports.encodeQr = encodeQr;
+exports.qrCodePng = qrCodePng;
+exports.qrCodeSvg = qrCodeSvg;
 exports.selectMode = selectMode;
-//# sourceMappingURL=chunk-AE53RKWR.cjs.map
-//# sourceMappingURL=chunk-AE53RKWR.cjs.map
+//# sourceMappingURL=chunk-CNWTYRZC.cjs.map
+//# sourceMappingURL=chunk-CNWTYRZC.cjs.map