preact-missing-hooks 4.2.0 → 4.4.0

package/dist/react.js

@@ -1692,6 +1692,90 @@ function useLLMMetadata(config) {
     ]);
 }
 
+const PRINT_CLASS = "use-ref-print-target";
+const PRINT_STYLE_ID = "use-ref-print-styles";
+const PRINT_CSS = `
+@media print {
+  body * {
+    visibility: hidden;
+  }
+  .${PRINT_CLASS},
+  .${PRINT_CLASS} * {
+    visibility: visible;
+  }
+  .${PRINT_CLASS} {
+    position: absolute !important;
+    left: 0 !important;
+    top: 0 !important;
+    width: 100% !important;
+  }
+}
+`;
+/**
+ * A Preact hook that binds a ref to a printable section and provides a function
+ * to print only that section using the native window.print() and @media print CSS.
+ * When print() is called (or user presses Ctrl+P after focusing that section), only
+ * the ref section is visible in the print layout. User can then print or save as PDF.
+ *
+ * @param printRef - Ref to the DOM element (e.g. a div) that should be printed.
+ * @param options - Optional: downloadAsPdf hint, documentTitle for the print document.
+ * @returns Object with a print() function.
+ *
+ * @example
+ * ```tsx
+ * function Report() {
+ *   const printRef = useRef<HTMLDivElement>(null);
+ *   const { print } = useRefPrint(printRef, { documentTitle: 'Report', downloadAsPdf: true });
+ *   return (
+ *     <div>
+ *       <div ref={printRef}>Content to print or save as PDF</div>
+ *       <button onClick={print}>Print / Save as PDF</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useRefPrint(printRef, options = {}) {
+    const { documentTitle } = options;
+    const originalTitleRef = react.useRef("");
+    const print = react.useCallback(() => {
+        const el = printRef.current;
+        if (!el || typeof window === "undefined" || !window.print) {
+            return;
+        }
+        // Ensure print-only styles exist (once per document)
+        let styleEl = document.getElementById(PRINT_STYLE_ID);
+        if (!styleEl) {
+            styleEl = document.createElement("style");
+            styleEl.id = PRINT_STYLE_ID;
+            styleEl.textContent = PRINT_CSS;
+            document.head.appendChild(styleEl);
+        }
+        el.classList.add(PRINT_CLASS);
+        if (documentTitle) {
+            originalTitleRef.current = document.title;
+            document.title = documentTitle;
+        }
+        const cleanup = () => {
+            el.classList.remove(PRINT_CLASS);
+            if (documentTitle && originalTitleRef.current !== undefined) {
+                document.title = originalTitleRef.current;
+            }
+        };
+        if ("onafterprint" in window) {
+            const onAfterPrint = () => {
+                cleanup();
+                window.removeEventListener("afterprint", onAfterPrint);
+            };
+            window.addEventListener("afterprint", onAfterPrint);
+        }
+        window.print();
+        // Fallback cleanup if afterprint is not fired (e.g. user cancels)
+        setTimeout(cleanup, 1000);
+    }, [printRef, documentTitle]);
+    return { print };
+}
+
 exports.useClipboard = useClipboard;
 exports.useEventBus = useEventBus;
 exports.useIndexedDB = useIndexedDB;
@@ -1700,6 +1784,7 @@ exports.useMutationObserver = useMutationObserver;
 exports.useNetworkState = useNetworkState;
 exports.usePreferredTheme = usePreferredTheme;
 exports.useRageClick = useRageClick;
+exports.useRefPrint = useRefPrint;
 exports.useThreadedWorker = useThreadedWorker;
 exports.useTransition = useTransition;
 exports.useWasmCompute = useWasmCompute;

package/dist/useRefPrint.d.ts

@@ -0,0 +1,39 @@
+import type { RefObject } from "preact";
+export interface UseRefPrintOptions {
+    /**
+     * When true, the print flow is triggered so the user can choose
+     * "Save as PDF" in the native print dialog. Uses the same window.print() path.
+     */
+    downloadAsPdf?: boolean;
+    /** Title for the print document (e.g. used when saving as PDF). */
+    documentTitle?: string;
+}
+export interface UseRefPrintReturn {
+    /** Triggers native print for the section bound to the ref (opens print dialog; only that section is printed via @media print). */
+    print: () => void;
+}
+/**
+ * A Preact hook that binds a ref to a printable section and provides a function
+ * to print only that section using the native window.print() and @media print CSS.
+ * When print() is called (or user presses Ctrl+P after focusing that section), only
+ * the ref section is visible in the print layout. User can then print or save as PDF.
+ *
+ * @param printRef - Ref to the DOM element (e.g. a div) that should be printed.
+ * @param options - Optional: downloadAsPdf hint, documentTitle for the print document.
+ * @returns Object with a print() function.
+ *
+ * @example
+ * ```tsx
+ * function Report() {
+ *   const printRef = useRef<HTMLDivElement>(null);
+ *   const { print } = useRefPrint(printRef, { documentTitle: 'Report', downloadAsPdf: true });
+ *   return (
+ *     <div>
+ *       <div ref={printRef}>Content to print or save as PDF</div>
+ *       <button onClick={print}>Print / Save as PDF</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useRefPrint(printRef: RefObject<HTMLElement | null>, options?: UseRefPrintOptions): UseRefPrintReturn;

package/docs/main.js

@@ -19,6 +19,7 @@ const {
   useWasmCompute,
   useWorkerNotifications,
   useLLMMetadata,
+  useRefPrint,
 } = await import(
   isLocal ? '../dist/index.module.js' : 'https://unpkg.com/preact-missing-hooks/dist/index.module.js'
 );
@@ -317,6 +318,29 @@ function DemoWorkerNotifications() {
   );
 }
 
+function DemoRefPrint() {
+  const printRef = useRef(null);
+  const { print } = useRefPrint(printRef, { documentTitle: 'Preact Missing Hooks — useRefPrint Demo', downloadAsPdf: true });
+  return h('div', {},
+    h('div', {
+      ref: printRef,
+      style: {
+        padding: '1rem',
+        background: 'var(--surface2)',
+        borderRadius: '6px',
+        marginBottom: '0.75rem',
+        border: '1px solid var(--border)',
+      },
+    }, [
+      h('strong', { style: { display: 'block', marginBottom: '0.5rem' } }, 'This section is printable'),
+      h('p', { style: { margin: 0, fontSize: '0.9rem', color: 'var(--text2)' } },
+        'Click "Print / Save as PDF" to open the native print dialog. You can print or choose "Save as PDF" as the destination.'
+      ),
+    ]),
+    h('button', { onClick: print }, 'Print / Save as PDF')
+  );
+}
+
 function DemoLLMMetadata() {
   const [route, setRoute] = useState('/');
   useLLMMetadata({
@@ -452,6 +476,13 @@ const HOOKS = [
     code: `const stats = useWorkerNotifications(worker, { maxHistory: 100 });\n// stats.progress, stats.runningTasks, stats.throughputPerSecond, ...`,
     Live: DemoWorkerNotifications,
   },
+  {
+    name: 'useRefPrint',
+    flow: 'ref + useRefPrint(ref, options?) → print() → native window.print() for that section',
+    summary: 'Binds a ref to a printable section and provides print() to open the native print dialog (user can save as PDF).',
+    code: `const printRef = useRef(null);\nconst { print } = useRefPrint(printRef, { documentTitle: 'My Doc', downloadAsPdf: true });\n// ... <div ref={printRef}>Content</div> ... <button onClick={print}>Print</button>`,
+    Live: DemoRefPrint,
+  },
   {
     name: 'useLLMMetadata',
     flow: 'Component → useLLMMetadata({ route, mode, title?, ... } | null) → <script type="application/llm+json" data-llm="true"> in <head>',