@ai-matrx/print 0.2.0 → 0.3.1

package/dist/react.d.cts

@@ -109,9 +109,25 @@ interface BlockPrinter {
      * data      — the block's structured data (serverData or parsed content)
      * variantId — which variant was chosen (undefined = default / no variants)
      * settings  — resolved setting values chosen by the user
+     *
+     * MAY resolve to a PrintOutcome ("opened" | "downloaded") so the host can
+     * tell the user when the popup-blocked download fallback fired; `void`
+     * stays legal for printers that don't go through a print window.
      */
-    print: (data: unknown, variantId?: string, settings?: PrintSettings) => void | Promise<void>;
+    print: (data: unknown, variantId?: string, settings?: PrintSettings) => void | PrintOutcome | Promise<void | PrintOutcome>;
 }
+/**
+ * How a print request actually reached the user.
+ *
+ * "opened"     — a print window/tab was opened and the document written into it.
+ * "downloaded" — the popup was blocked, so the document was downloaded as an
+ *                .html file instead (the contract's fallback). Hosts SHOULD
+ *                surface this to the user (e.g. a toast saying the print file
+ *                was downloaded) — a blocked popup plus a silent download is
+ *                indistinguishable from "nothing happened", which is exactly
+ *                how QA filed it (2026-08-30, F5/F6/F8).
+ */
+type PrintOutcome = "opened" | "downloaded";
 
 /**
  * @ai-matrx/print/labels — the label-sheet engine.
@@ -258,18 +274,25 @@ interface PrintOptionsDialogProps {
     data: unknown;
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /**
+     * Fired after printer.print() settles, with the PrintOutcome when the
+     * printer reports one. "downloaded" means the popup was blocked and the
+     * print document was saved as an .html download instead — hosts should
+     * toast that, or the fallback is indistinguishable from nothing happening.
+     */
+    onPrinted?: (outcome: void | PrintOutcome) => void;
 }
 /**
  * Shared pre-print options UI — shown when a BlockPrinter has variants or settings.
  * Desktop: Dialog. Mobile: Drawer (bottom sheet).
  */
-declare function PrintOptionsDialog({ printer, data, open, onOpenChange, }: PrintOptionsDialogProps): React.JSX.Element;
+declare function PrintOptionsDialog({ printer, data, open, onOpenChange, onPrinted, }: PrintOptionsDialogProps): React.JSX.Element;
 /**
  * Manages open state for PrintOptionsDialog.
  * If the printer has variants or settings, shows the dialog.
  * If it has neither, calls printer.print() immediately with no settings.
  */
-declare function usePrintOptions(printer: BlockPrinter | null, data: unknown): {
+declare function usePrintOptions(printer: BlockPrinter | null, data: unknown, onPrinted?: (outcome: void | PrintOutcome) => void): {
     open: boolean;
     setOpen: React.Dispatch<React.SetStateAction<boolean>>;
     triggerPrint: () => Promise<void>;

package/dist/react.d.ts

@@ -109,9 +109,25 @@ interface BlockPrinter {
      * data      — the block's structured data (serverData or parsed content)
      * variantId — which variant was chosen (undefined = default / no variants)
      * settings  — resolved setting values chosen by the user
+     *
+     * MAY resolve to a PrintOutcome ("opened" | "downloaded") so the host can
+     * tell the user when the popup-blocked download fallback fired; `void`
+     * stays legal for printers that don't go through a print window.
      */
-    print: (data: unknown, variantId?: string, settings?: PrintSettings) => void | Promise<void>;
+    print: (data: unknown, variantId?: string, settings?: PrintSettings) => void | PrintOutcome | Promise<void | PrintOutcome>;
 }
+/**
+ * How a print request actually reached the user.
+ *
+ * "opened"     — a print window/tab was opened and the document written into it.
+ * "downloaded" — the popup was blocked, so the document was downloaded as an
+ *                .html file instead (the contract's fallback). Hosts SHOULD
+ *                surface this to the user (e.g. a toast saying the print file
+ *                was downloaded) — a blocked popup plus a silent download is
+ *                indistinguishable from "nothing happened", which is exactly
+ *                how QA filed it (2026-08-30, F5/F6/F8).
+ */
+type PrintOutcome = "opened" | "downloaded";
 
 /**
  * @ai-matrx/print/labels — the label-sheet engine.
@@ -258,18 +274,25 @@ interface PrintOptionsDialogProps {
     data: unknown;
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /**
+     * Fired after printer.print() settles, with the PrintOutcome when the
+     * printer reports one. "downloaded" means the popup was blocked and the
+     * print document was saved as an .html download instead — hosts should
+     * toast that, or the fallback is indistinguishable from nothing happening.
+     */
+    onPrinted?: (outcome: void | PrintOutcome) => void;
 }
 /**
  * Shared pre-print options UI — shown when a BlockPrinter has variants or settings.
  * Desktop: Dialog. Mobile: Drawer (bottom sheet).
  */
-declare function PrintOptionsDialog({ printer, data, open, onOpenChange, }: PrintOptionsDialogProps): React.JSX.Element;
+declare function PrintOptionsDialog({ printer, data, open, onOpenChange, onPrinted, }: PrintOptionsDialogProps): React.JSX.Element;
 /**
  * Manages open state for PrintOptionsDialog.
  * If the printer has variants or settings, shows the dialog.
  * If it has neither, calls printer.print() immediately with no settings.
  */
-declare function usePrintOptions(printer: BlockPrinter | null, data: unknown): {
+declare function usePrintOptions(printer: BlockPrinter | null, data: unknown, onPrinted?: (outcome: void | PrintOutcome) => void): {
     open: boolean;
     setOpen: React.Dispatch<React.SetStateAction<boolean>>;
     triggerPrint: () => Promise<void>;

package/dist/react.js

@@ -11,8 +11,8 @@ import { twMerge } from "tailwind-merge";
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
-function openPrintWindow(htmlDocument, filename = "print") {
-  const win = window.open("", "_blank", "width=920,height=720,scrollbars=yes");
+function openPrintWindow(htmlDocument, filename = "print", windowFeatures = "width=920,height=720,scrollbars=yes") {
+  const win = window.open("", "_blank", windowFeatures);
   if (!win) {
     const blob = new Blob([htmlDocument], { type: "text/html;charset=utf-8" });
     const url = URL.createObjectURL(blob);
@@ -22,12 +22,13 @@ function openPrintWindow(htmlDocument, filename = "print") {
     document.body.appendChild(a);
     a.click();
     document.body.removeChild(a);
-    URL.revokeObjectURL(url);
-    return;
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+    return "downloaded";
   }
   win.document.open();
   win.document.write(htmlDocument);
   win.document.close();
+  return "opened";
 }
 
 // src/qr.ts
@@ -555,7 +556,7 @@ ${bodyHtml}
 ${withFitScript ? LP_FIT_SCRIPT : ""}
 </body>
 </html>`;
-  openPrintWindow(html, title);
+  return openPrintWindow(html, title);
 }
 function expandLabels(labels, s) {
   const from = s.rangeFrom > 0 ? s.rangeFrom : 1;
@@ -593,7 +594,7 @@ function buildCalibrationBody(t) {
   return `<div class="lp-page">${banner}${marks}${cells.join("\n")}</div>`;
 }
 function printCalibrationSheet(template) {
-  openSheetWindow(
+  return openSheetWindow(
     template,
     buildCalibrationBody(template),
     "Label calibration",
@@ -660,18 +661,16 @@ async function printQrLabelSheet(data, variantId, rawSettings) {
   const t = resolveTemplate(data, variantId);
   const s = resolveSettings(rawSettings);
   if (s.calibrationPage) {
-    printCalibrationSheet(t);
-    return;
+    return printCalibrationSheet(t);
   }
   const labels = expandLabels(data.labels ?? [], s);
   if (!labels.length) {
-    openSheetWindow(
+    return openSheetWindow(
       t,
       `<div class="lp-page"><div style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:11pt;">No labels to print.</div></div>`,
       "QR labels",
       false
     );
-    return;
   }
   const hasBadge = labels.some((l) => (l.badge ?? "").trim() !== "");
   const layout = computeCellLayout(t, s.showCaption, hasBadge);
@@ -701,7 +700,7 @@ async function printQrLabelSheet(data, variantId, rawSettings) {
   const tail = cells.length % perPage;
   if (tail > 0)
     for (let i = 0; i < perPage - tail; i++) cells.push({ html: "" });
-  openSheetWindow(
+  return openSheetWindow(
     t,
     renderPages(t, cells),
     "QR labels",
@@ -1101,7 +1100,8 @@ function visibleSettings(settings, variantId) {
 function PrintOptionsContent({
   printer,
   data,
-  onClose
+  onClose,
+  onPrinted
 }) {
   const [selectedVariant, setSelectedVariant] = useState(
     printer.variants[0]?.id ?? ""
@@ -1125,7 +1125,8 @@ function PrintOptionsContent({
     setIsPrinting(true);
     try {
       const settings = useDefaults ? buildDefaultSettings(allSettings) : settingValues;
-      await printer.print(data, variantId, settings);
+      const outcome = await printer.print(data, variantId, settings);
+      onPrinted?.(outcome);
     } finally {
       setIsPrinting(false);
       onClose();
@@ -1353,7 +1354,8 @@ function PrintOptionsDialog({
   printer,
   data,
   open,
-  onOpenChange
+  onOpenChange,
+  onPrinted
 }) {
   const isMobile = useIsMobile();
   const handleClose = () => onOpenChange(false);
@@ -1380,7 +1382,8 @@ function PrintOptionsDialog({
         {
           printer,
           data,
-          onClose: handleClose
+          onClose: handleClose,
+          onPrinted
         }
       ) })
     ] }) });
@@ -1398,18 +1401,20 @@ function PrintOptionsDialog({
       {
         printer,
         data,
-        onClose: handleClose
+        onClose: handleClose,
+        onPrinted
       }
     ) })
   ] }) });
 }
-function usePrintOptions(printer, data) {
+function usePrintOptions(printer, data, onPrinted) {
   const [open, setOpen] = useState(false);
   const triggerPrint = async () => {
     if (!printer) return;
     const hasOptions = printer.variants.length > 0 || (printer.settings?.length ?? 0) > 0;
     if (!hasOptions) {
-      await printer.print(data);
+      const outcome = await printer.print(data);
+      onPrinted?.(outcome);
     } else {
       setOpen(true);
     }