preact-missing-hooks 4.2.0 → 4.4.0

package/llm.package.txt

@@ -1,5 +1,5 @@
 Package: preact-missing-hooks
-Version: 4.1.0
+Version: 4.2.0
 
 Description:
 A lightweight, extendable collection of missing React-like hooks for Preact — plus fresh, powerful new ones designed specifically for modern Preact apps.
@@ -40,48 +40,48 @@ Related packages:
 preact, react, react-hooks, preact/hooks
 
 Exports:
-- ConnectionType : TypeScript type representing the physical connection type of the device (e.g., 'wifi', 'cellular', 'ethernet', 'none', 'unknown'). Used to determine how the device is connected to the network, which can inform decisions about data usage and performance optimizations.
-- EffectiveConnectionType : TypeScript type representing the effective connection type as defined by the Network Information API. Represents the effective connection type ('slow-2g', '2g', '3g', '4g') that the browser uses to optimize content delivery based on the user's network conditions.
-- IDBController : A class that manages IndexedDB connections and operations, providing methods to open, close, and interact with IndexedDB databases. Used for encapsulating IndexedDB logic and handling database lifecycle. — params: config: IndexedDBConfig — returns: Instance of IDBController — e.g. const db = new IDBController({ name: 'my-db' })
-- IndexedDBConfig : Configuration object for setting up an IndexedDB connection, including database name, version, and optional upgrade callback. Used to customize the IndexedDB environment for use with the IDBController. — params: { name: string, version?: number, upgradeCallback?: (db: IDBDatabase) => void } — returns: None (type definition)
-- InjectableProps : A TypeScript type that defines the shape of props that can be injected into a component, typically used for dependency injection or prop forwarding. — params: Generic type extending React.PropsWithChildren — returns: N/A
-- LLMConfig : Configuration object type for LLM integrations, defining required settings like model, API key, and optional parameters. Used to initialize and configure LLM client instances with consistent type safety. — params: { model: string, apiKey: string, temperature?: number, maxTokens?: number } — returns: LLMConfig object with typed properties for LLM initialization
-- LLMPayload : Payload type for LLM requests, encapsulating the user message and optional context for AI model interactions. Used to structure input data sent to LLM endpoints for processing and response generation. — params: { message: string, context?: string[] } — returns: LLMPayload object containing message and optional context array for LLM processing
-- NetworkState : TypeScript interface defining the structure of network state information returned by useNetworkState hook. Includes properties like online (boolean), since (Date), downlink (number), downlinkMax (number), effectiveType (EffectiveConnectionType), rtt (number), and type (ConnectionType).
-- OGType : Type definition for Open Graph metadata types used in social media sharing. — params: N/A — returns: N/A
-- PreferredTheme : A TypeScript type that defines the possible values for a preferred theme, typically 'light', 'dark', or 'no-preference'. — params: N/A — returns: 'light' | 'dark' | 'no-preference'
-- RageClickPayload : TypeScript type defining the shape of a rage click event payload. Contains properties like target element, coordinates, and timestamp to identify rapid repeated clicks on the same element. — params: Optional: { target: Element, x: number, y: number, timestamp: number } — returns: N/A
-- RunOptions : TypeScript type defining options for running threaded operations. Controls execution behavior like cancellation, timeout, and result handling for worker tasks. — params: Optional: { cancelable?: boolean, timeout?: number, onResult?: (result: any) => void } — returns: N/A
-- ThreadedWorkerMode : TypeScript enum defining operational modes for threaded workers. Specifies whether worker runs in dedicated, shared, or service worker context for different threading strategies. — params: Optional: { DEDICATED, SHARED, SERVICE_WORKER } — returns: N/A
-- useClipboard (Hook) : React hook that provides access to the system clipboard, allowing reading and writing of text content. Useful for implementing copy-to-clipboard functionality in components without requiring direct DOM manipulation or event handling. — params: options?: UseClipboardOptions — returns: UseClipboardReturn object with read and write methods — e.g. const { write } = useClipboard(); write('Hello World');
-- UseClipboardOptions : TypeScript type defining optional configuration for the useClipboard hook, such as specifying the target element for clipboard operations or setting permissions for clipboard access.
-- UseClipboardReturn : TypeScript interface defining the return value of useClipboard hook, which includes read and write methods for interacting with the system clipboard. The read method returns the current clipboard content as a string, while the write method sets new content to the clipboard.
-- useEventBus (Hook) : A hook that provides access to a global event bus for publishing and subscribing to events across components. It returns an object with methods to subscribe, unsubscribe, and publish events. — params: none — returns: { subscribe: (event: string, callback: Function) => void, unsubscribe: (event: string, callback: Function) => void, publish: (event: string, data: any) => void }
-- useIndexedDB (Hook) : React hook providing simplified IndexedDB access with React state management. Enables reading and writing to IndexedDB with automatic change detection and error handling. — params: databaseName: string, storeName: string, options?: { version?: number, keyPath?: string } — returns: UseIndexedDBReturn — e.g. const { data, error, isLoading, add, get } = useIndexedDB('myDB', 'store')
-- UseIndexedDBReturn : Return type for the useIndexedDB hook, containing the database instance and a loading/error state. Used to provide the current IndexedDB state and data to React components. — params: { db: IDBDatabase | null, loading: boolean, error: Error | null } — returns: None (type definition)
-- useLLMMetadata (Hook) : React hook for fetching and managing LLM metadata within a component's lifecycle. — params: options?: { modelId?: string } — returns: { metadata: LLMData | null, loading: boolean, error: Error | null } — e.g. const { metadata, loading } = useLLMMetadata({ modelId: 'gpt-4' });
-- useMutationObserver (Hook) : A hook that creates and manages a MutationObserver to watch for changes in the DOM. It accepts a target element and a callback to execute when mutations are observed, returning a ref to attach to the target element. — params: target: Element | null, callback: MutationCallback, options?: MutationObserverInit — returns: ref: { current: Element | null }
-- UseMutationObserverOptions : A TypeScript type defining the options object for the useMutationObserver hook, extending MutationObserverInit to include optional configuration for observing DOM mutations. — params: extends MutationObserverInit — returns: N/A
-- useNetworkState (Hook) : React hook that returns the current network state of the browser, including connection type, effective connection type, and whether the device is online or offline. Useful for adapting application behavior based on network conditions, such as reducing data usage or showing offline indicators. — params: none — returns: NetworkState object with online, since, downlink, downlinkMax, effectiveType, rtt, type properties — e.g. const network = useNetworkState(); if (!network.online) { /* show offline message */ }
-- usePreferredTheme (Hook) : A hook that detects and returns the user's preferred color scheme (light or dark) based on the operating system or browser settings. It returns the current preferred theme. — params: none — returns: 'light' | 'dark' | 'no-preference'
-- useRageClick (Hook) : React hook that detects rapid, repeated clicking (rage clicking) on an element, typically indicating user frustration or confusion. Useful for identifying problematic UI elements that may need redesign or additional feedback to improve user experience. — params: options?: { threshold?: number, timeout?: number } — returns: { isRageClicking: boolean, reset: () => void } — e.g. const { isRageClicking } = useRageClick(); if (isRageClicking) { /* show help tooltip */ }
-- UseRageClickOptions : TypeScript type defining configuration options for the useRageClick hook. Allows customizing detection threshold, debounce delay, and callback behavior for rage click detection. — params: Optional: { threshold?: number, debounce?: number, callback?: (payload: RageClickPayload) => void } — returns: N/A
-- useThreadedWorker (Hook) : React hook that manages communication with a web worker thread. Enables offloading heavy computations to a separate thread while maintaining React state synchronization. — params: options: UseThreadedWorkerOptions — returns: UseThreadedWorkerReturn — e.g. const { data, error, isLoading } = useThreadedWorker({ worker: myWorker, input: someData })
-- UseThreadedWorkerOptions : TypeScript type defining configuration options for useThreadedWorker hook. Includes worker instance, input data, transfer options, and error handling callbacks. — params: Optional: { worker: Worker, input?: any, transfer?: Transferable[], onError?: (error: Error) => void } — returns: N/A
-- UseThreadedWorkerReturn : TypeScript type defining the return value shape from useThreadedWorker hook. Contains data, error state, loading status, and control methods for worker communication. — params: Optional: { data: any, error: Error | null, isLoading: boolean, cancel: () => void, postMessage: (message: any) => void } — returns: N/A
-- useTransition (Hook) : A custom hook that wraps React's useTransition API, providing a way to mark updates as transitions to allow the browser to prioritize updates. It returns a tuple containing a boolean indicating if the transition is pending and a startTransition function to wrap state updates. — params: config?: { timeoutMs?: number } — returns: [isPending: boolean, startTransition: (callback: () => void) => void]
-- useWasmCompute (Hook) : A React hook that loads and executes WebAssembly modules for computationally intensive tasks, providing a way to run WASM code in the browser. Used for offloading heavy computations to WASM for performance gains. — params: options: UseWasmComputeOptions — returns: function that executes the WASM module with input data — e.g. const compute = useWasmCompute({ modulePath: '/compute.wasm' }); const result = compute(inputData)
-- UseWasmComputeOptions : Options object for configuring the useWasmCompute hook, including the path to the WASM module and optional initialization parameters. Used to specify which WASM module to load and how to initialize it. — params: { modulePath: string, initParams?: any } — returns: None (type definition)
-- UseWasmComputeReturn : Type definition for the return value of Wasm compute functions, typically containing status and result fields. — params: N/A — returns: N/A
-- useWebRTCIP (Hook) : A React hook that retrieves the local IP address using WebRTC by creating a peer connection and extracting the IP from ICE candidates. Used for obtaining the client's IP address in a browser environment. — params: options?: UseWebRTCIPOptions — returns: UseWebRTCIPReturn — e.g. const { ip, loading, error } = useWebRTCIP()
-- UseWebRTCIPOptions : Options object for configuring the useWebRTCIP hook, such as disabling IPv6 or setting a timeout. Used to customize the behavior of the WebRTC IP discovery process. — params: { disableIPv6?: boolean, timeout?: number } — returns: None (type definition)
-- UseWebRTCIPReturn : Return type for the useWebRTCIP hook, containing the discovered IP address and loading/error state. Used to provide the WebRTC IP discovery result to React components. — params: { ip: string | null, loading: boolean, error: Error | null } — returns: None (type definition)
-- useWorkerNotifications (Hook) : React hook that subscribes to worker notifications and manages their lifecycle within a component. — params: options: UseWorkerNotificationsOptions — returns: UseWorkerNotificationsReturn — e.g. const { notifications, error } = useWorkerNotifications({ worker: myWorker });
-- UseWorkerNotificationsOptions : Configuration options for the useWorkerNotifications hook, including worker instance and event filters. — params: N/A — returns: N/A
-- UseWorkerNotificationsReturn : Return type for useWorkerNotifications hook, providing notifications array and error state. — params: N/A — returns: N/A
-- useWrappedChildren (Hook) : A hook that wraps the children of a component with a specified wrapper component or element. It takes children and a wrapper as arguments and returns the wrapped children. — params: children: ReactNode, wrapper: ComponentType | string — returns: ReactNode
-- WorkerEventType : Enumeration type defining the different types of events that can be emitted by a worker. — params: N/A — returns: N/A
-- WorkerNotificationEvent : Type definition for worker notification events, containing event data and metadata. — params: N/A — returns: N/A
+- ConnectionType : TypeScript type representing the connection type as defined by the Network Information API. It includes values like 'bluetooth', 'cellular', 'ethernet', 'wifi', 'wimax', 'none', 'unknown', 'other' that indicate the physical connection type. — e.g. 'bluetooth' | 'cellular' | 'ethernet' | 'wifi' | 'wimax' | 'none' | 'unknown' | 'other'
+- EffectiveConnectionType : TypeScript type representing the effective connection type as defined by the Network Information API. It includes values like 'slow-2g', '2g', '3g', '4g' that indicate the effective network speed the browser detects. — e.g. 'slow-2g' | '2g' | '3g' | '4g'
+- IDBController : Controller class managing IndexedDB instance lifecycle, providing methods to open, close, and interact with the database. Use when you need programmatic control over IndexedDB operations beyond basic hooks. — params: constructor(config: IndexedDBConfig) — returns: IDBController instance with open(), close(), getStore(), and transaction methods
+- IndexedDBConfig : Configuration object for IndexedDB operations, specifying database name, version, and store schema. Use when setting up persistent client-side storage with custom store structures. — params: { dbName: string, version?: number, stores: { name: string, keyPath?: string, autoIncrement?: boolean }[] }
+- InjectableProps : An interface defining the props that can be injected into a component. It is used to specify the properties that can be dynamically added to a component. — params: N/A — returns: N/A
+- LLMConfig : Configuration object for setting up an LLM client, including model details, API keys, and connection parameters. Use this to define how the LLM should behave and connect. — params: Optional: { model: string, apiKey: string, endpoint: string, temperature?: number, maxTokens?: number } — returns: A typed configuration object for LLM initialization — e.g. const config: LLMConfig = { model: 'gpt-4', apiKey: 'your-key', endpoint: 'https://api.openai.com/v1' }
+- LLMPayload : Payload structure for sending requests to an LLM, containing the prompt, conversation context, and optional parameters. Use this to format data sent to the LLM service. — params: Optional: { prompt: string, messages?: Message[], temperature?: number, maxTokens?: number, stream?: boolean } — returns: A typed payload object for LLM requests — e.g. const payload: LLMPayload = { prompt: 'Translate to French:', messages: [{ role: 'user', content: 'Hello world' }] }
+- NetworkState : TypeScript type representing the complete network state object returned by useNetworkState hook. It includes online status, timestamps, bandwidth information, effective connection type, round-trip time, data saver status, and connection type. — e.g. { online: boolean, since: number, downlink: number, downlinkMax: number, effectiveType: EffectiveConnectionType, rtt: number, saveData: boolean, type: ConnectionType }
+- OGType : Type definition for Open Graph metadata types. Represents the standardized vocabulary for social media sharing metadata, used to control how content appears when shared on platforms like Facebook and Twitter.
+- PreferredTheme : A type alias for the possible theme values ('light' or 'dark'). It is used to ensure type safety when working with theme-related values. — params: N/A — returns: N/A
+- RageClickPayload : Interface describing the payload structure for rage click events, typically containing timestamp, element info, and click count. Used when tracking rapid repeated clicks for UX analysis or error reporting.
+- RunOptions : Options object for controlling execution behavior of threaded operations, including timeout settings, retry logic, and error handling strategies. Used to customize how tasks run in worker threads.
+- ThreadedWorkerMode : Enumeration defining worker modes: 'shared' for SharedWorker instances or 'dedicated' for standard Web Workers. Determines how worker threads are instantiated and shared across components.
+- useClipboard (Hook) : React hook that provides access to the system clipboard, allowing reading and writing of clipboard content. It returns an object with methods to read and write text to the clipboard, handling browser compatibility and permissions. — params: options?: UseClipboardOptions — returns: UseClipboardReturn: { readText: () => Promise<string>, writeText: (text: string) => Promise<void> } — e.g. const { readText, writeText } = useClipboard()
+- UseClipboardOptions : TypeScript type representing the options object for the useClipboard hook. Currently it may include configuration options for clipboard behavior, though the exact properties depend on the implementation. — e.g. {}
+- UseClipboardReturn : TypeScript type representing the return value of the useClipboard hook. It includes readText and writeText methods that return promises for asynchronous clipboard operations. — e.g. { readText: () => Promise<string>, writeText: (text: string) => Promise<void> }
+- useEventBus (Hook) : A hook that provides a simple event bus for component communication. It allows components to emit and listen to events without prop drilling. — params: N/A — returns: Object with emit and on methods for event handling
+- useIndexedDB (Hook) : Hook for managing IndexedDB database operations including opening connections, reading, writing, and deleting data. Provides reactive state management for database changes and error handling. — params: dbName: string, options?: { version?: number, objectStores?: string[] } — returns: { db: IDBDatabase | null, error: Error | null, isOpen: boolean, close: () => void } — e.g. const { db, isOpen, error } = useIndexedDB('myDatabase');
+- UseIndexedDBReturn : Return type from useIndexedDB hook containing database instance, store references, and utility methods. Use to access structured data operations and transaction capabilities within React components. — params: { db: IDBDatabase, stores: Record<string, IDBObjectStore>, transaction: (stores: string[], mode?: IDBTransactionMode) => IDBTransaction }
+- useLLMMetadata (Hook) : React hook that retrieves metadata about the underlying LLVM/WebAssembly compilation environment. Provides information about the current runtime capabilities, version, and available features for debugging and optimization. — returns: object containing metadata properties — e.g. const metadata = useLLMMetadata()
+- useMutationObserver (Hook) : A hook that observes DOM mutations on a given element and calls a callback when mutations occur. It is useful for reacting to changes in the DOM structure or attributes. — params: element: Element, callback: (mutations: MutationRecord[]) => void, options?: MutationObserverInit — returns: void
+- UseMutationObserverOptions : An interface defining the options for the useMutationObserver hook. It extends MutationObserverInit and includes additional properties specific to the hook. — params: N/A — returns: N/A
+- useNetworkState (Hook) : React hook that returns the current network state of the device, including connection type, effective connection type, and whether the device is online or offline. It uses the browser's Network Information API to provide real-time updates when the network conditions change. — params: options?: { refreshRate?: number } — returns: NetworkState: { online: boolean, since: number, downlink: number, downlinkMax: number, effectiveType: EffectiveConnectionType, rtt: number, saveData: boolean, type: ConnectionType } — e.g. const { online, type, effectiveType } = useNetworkState()
+- usePreferredTheme (Hook) : A hook that provides the user's preferred theme (light or dark) based on system preferences or user settings. It is useful for implementing theme-aware components. — params: N/A — returns: String representing the preferred theme ('light' or 'dark')
+- useRageClick (Hook) : React hook that detects rapid, repeated clicks on an element, commonly known as rage clicks. It helps identify user frustration by tracking multiple clicks in quick succession and provides a callback when such behavior is detected. — params: options?: { threshold?: number, timeWindow?: number, callback?: (event: MouseEvent) => void } — returns: void — e.g. useRageClick({ threshold: 3, timeWindow: 1000, callback: (event) => console.log('Rage click detected!') })
+- UseRageClickOptions : Configuration options for the useRageClick hook, including threshold for clicks per second, timeout duration, and callback handler. Allows customization of rage click detection sensitivity and behavior.
+- useThreadedWorker (Hook) : Hook that creates and manages a Web Worker thread for offloading heavy computations or operations. Returns worker instance and control methods for communication and lifecycle management. — params: options: UseThreadedWorkerOptions — returns: UseThreadedWorkerReturn — e.g. const { worker, postMessage, terminate } = useThreadedWorker({ worker: myWorker });
+- UseThreadedWorkerOptions : Configuration object for useThreadedWorker hook containing worker script URL or blob, mode selection, and optional initialization parameters. Defines how the worker thread should be created and configured.
+- UseThreadedWorkerReturn : Return type from useThreadedWorker hook containing worker instance, message posting method, event listeners, and cleanup functions. Provides complete interface for interacting with the managed worker thread.
+- useTransition (Hook) : A hook that provides a transition state and a function to start a transition. It is used to defer non-urgent updates to avoid blocking the UI during high-priority updates. — params: options?: { timeoutMs?: number } — returns: Array containing a boolean indicating if a transition is in progress and a function to start a transition
+- useWasmCompute (Hook) : Hook that loads and executes WebAssembly modules for high-performance computation in the browser. Use when you need to run CPU-intensive tasks like image processing, cryptography, or numerical computations without blocking the main thread. — params: options: UseWasmComputeOptions — returns: Promise resolving to Wasm module instance with exported functions
+- UseWasmComputeOptions : Configuration object for useWasmCompute hook specifying WASM module source, imports, and execution parameters. Use to configure memory limits, import objects, and execution environment for WebAssembly modules. — params: { moduleUrl: string, imports?: Record<string, any>, memorySize?: number }
+- UseWasmComputeReturn : Type definition for the return value of a WASM compute function. Represents the structured result of a WebAssembly-based computation, typically containing status, data, and error information.
+- useWebRTCIP (Hook) : Hook that retrieves local WebRTC IP addresses by creating a peer connection and parsing ICE candidates. Use when you need to detect client IP addresses for WebRTC signaling or network diagnostics. — params: options?: UseWebRTCIPOptions — returns: UseWebRTCIPReturn containing ipAddresses: string[] and loading: boolean
+- UseWebRTCIPOptions : Configuration options for useWebRTCIP hook, allowing customization of timeout duration and STUN/TURN server configuration. Use to control how long the hook waits for ICE gathering and which servers to use. — params: { timeout?: number, iceServers?: RTCIceServer[] }
+- UseWebRTCIPReturn : Return object from useWebRTCIP hook containing detected IP addresses and loading state. Use to access the gathered IP addresses and determine when the operation is complete. — params: { ipAddresses: string[], loading: boolean }
+- useWorkerNotifications (Hook) : React hook that subscribes to notifications from a Web Worker. Provides real-time updates from background processing tasks, allowing components to react to worker events without manual event listener management. — params: options: UseWorkerNotificationsOptions — returns: UseWorkerNotificationsReturn — e.g. const { notifications, error } = useWorkerNotifications({ worker: myWorker })
+- UseWorkerNotificationsOptions : Configuration object type for the useWorkerNotifications hook. Specifies parameters like the worker instance, event filters, and optional callback handlers for customizing notification subscription behavior.
+- UseWorkerNotificationsReturn : Return type for the useWorkerNotifications hook. Provides an object containing the current notifications array, error state, and optional methods for managing the subscription to worker events.
+- useWrappedChildren (Hook) : A hook that wraps child components with additional functionality or styling. It is useful for applying consistent behavior or appearance to a group of child components. — params: children: ReactNode, wrapper: (child: ReactNode) => ReactNode — returns: ReactNode
+- WorkerEventType : Enumeration of possible event types that can be emitted by a Web Worker. Defines the standard set of notification categories for worker-to-main-thread communication, enabling type-safe event handling.
+- WorkerNotificationEvent : Type definition for a worker notification event object. Contains metadata about a specific event from a Web Worker, including type, timestamp, and payload data for structured communication.
 
 Hooks:
 - useTransition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-missing-hooks",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "A lightweight, extendable collection of missing React-like hooks for Preact — plus fresh, powerful new ones designed specifically for modern Preact apps.",
   "author": "Prakhar Dubey",
   "license": "MIT",
@@ -82,6 +82,11 @@
       "import": "./dist/useWorkerNotifications.module.js",
       "require": "./dist/useWorkerNotifications.js"
     },
+    "./useRefPrint": {
+      "types": "./dist/useRefPrint.d.ts",
+      "import": "./dist/useRefPrint.module.js",
+      "require": "./dist/useRefPrint.js"
+    },
     "./react": {
       "types": "./dist/index.d.ts",
       "import": "./dist/react.module.js",

package/src/index.ts

@@ -12,3 +12,4 @@ export * from "./useWebRTCIP";
 export * from "./useWasmCompute";
 export * from "./useWorkerNotifications";
 export * from "./useLLMMetadata";
+export * from "./useRefPrint";

package/src/useRefPrint.ts

@@ -0,0 +1,116 @@
+import type { RefObject } from "preact";
+import { useCallback, useRef } from "preact/hooks";
+
+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;
+  }
+}
+`;
+
+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 function useRefPrint(
+  printRef: RefObject<HTMLElement | null>,
+  options: UseRefPrintOptions = {}
+): UseRefPrintReturn {
+  const { documentTitle } = options;
+  const originalTitleRef = useRef<string>("");
+
+  const print = 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
+    ) as HTMLStyleElement | null;
+    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 };
+}

package/tests/useRefPrint.test.tsx

@@ -0,0 +1,115 @@
+/** @jsx h */
+import { h } from "preact";
+import { useRef } from "preact/hooks";
+import { render, fireEvent } from "@testing-library/preact";
+import { useRefPrint } from "../src/useRefPrint";
+import { vi } from "vitest";
+
+const PRINT_CLASS = "use-ref-print-target";
+const PRINT_STYLE_ID = "use-ref-print-styles";
+
+describe("useRefPrint", () => {
+  let mockPrint: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockPrint = vi.fn();
+    vi.spyOn(globalThis.window, "print").mockImplementation(mockPrint);
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    document.getElementById(PRINT_STYLE_ID)?.remove();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("returns a print function", () => {
+    function TestComponent() {
+      const ref = useRef<HTMLDivElement>(null);
+      const { print } = useRefPrint(ref);
+      return (
+        <div>
+          <div ref={ref}>Content</div>
+          <button onClick={print}>Print</button>
+        </div>
+      );
+    }
+    const { getByText } = render(<TestComponent />);
+    expect(getByText("Print")).toBeDefined();
+  });
+
+  it("adds print class and injects @media print styles then calls window.print when print is clicked", () => {
+    function TestComponent() {
+      const ref = useRef<HTMLDivElement>(null);
+      const { print } = useRefPrint(ref);
+      return (
+        <div>
+          <div ref={ref} data-testid="print-area">
+            <p>Section to print</p>
+          </div>
+          <button onClick={print}>Print</button>
+        </div>
+      );
+    }
+    const { getByText, getByTestId } = render(<TestComponent />);
+    const printArea = getByTestId("print-area");
+    expect(printArea).toBeTruthy();
+
+    fireEvent.click(getByText("Print"));
+
+    expect(printArea.classList.contains(PRINT_CLASS)).toBe(true);
+    const styleEl = document.getElementById(PRINT_STYLE_ID);
+    expect(styleEl).toBeTruthy();
+    expect(styleEl?.textContent).toContain("@media print");
+    expect(styleEl?.textContent).toContain(PRINT_CLASS);
+    expect(mockPrint).toHaveBeenCalled();
+  });
+
+  it("does nothing when ref.current is null", () => {
+    function TestComponent() {
+      const ref = useRef<HTMLDivElement>(null);
+      const { print } = useRefPrint(ref);
+      return <button onClick={print}>Print</button>;
+    }
+    const { getByText } = render(<TestComponent />);
+    fireEvent.click(getByText("Print"));
+    expect(mockPrint).not.toHaveBeenCalled();
+    expect(document.getElementById(PRINT_STYLE_ID)).toBeNull();
+  });
+
+  it("sets document.title when documentTitle option is provided and restores after print", () => {
+    const originalTitle = document.title;
+    function TestComponent() {
+      const ref = useRef<HTMLDivElement>(null);
+      const { print } = useRefPrint(ref, { documentTitle: "My Report" });
+      return (
+        <div>
+          <div ref={ref}>Content</div>
+          <button onClick={print}>Print</button>
+        </div>
+      );
+    }
+    const { getByText } = render(<TestComponent />);
+    fireEvent.click(getByText("Print"));
+    expect(document.title).toBe("My Report");
+    // Simulate afterprint to trigger cleanup
+    window.dispatchEvent(new Event("afterprint"));
+    expect(document.title).toBe(originalTitle);
+  });
+
+  it("calls window.print when print is invoked", () => {
+    function TestComponent() {
+      const ref = useRef<HTMLDivElement>(null);
+      const { print } = useRefPrint(ref);
+      return (
+        <div>
+          <div ref={ref}>Content</div>
+          <button onClick={print}>Print</button>
+        </div>
+      );
+    }
+    const { getByText } = render(<TestComponent />);
+    fireEvent.click(getByText("Print"));
+    expect(mockPrint).toHaveBeenCalled();
+  });
+});