cliphook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 satishjaiswal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# cliphook 🪝
+
+A lightweight, developer-friendly React hook + component for easy clipboard management with built-in feedback states and no-conflict naming.
+
+[![npm version](https://img.shields.io/npm/v/cliphook.svg?style=flat-square)](https://www.npmjs.com/package/cliphook)
+[![npm downloads](https://img.shields.io/npm/dm/cliphook.svg?style=flat-square)](https://www.npmjs.com/package/cliphook)
+[![license](https://img.shields.io/npm/l/cliphook.svg?style=flat-square)](https://www.npmjs.com/package/cliphook)
+
+## ✨ Why cliphook?
+
+- **Zero Dependencies**: Keeps your bundle size ultra-small.
+- **Robust Fallback**: Uses `navigator.clipboard` with an automatic fallback to `document.execCommand('copy')` for older browsers.
+- **No-Conflict Naming**: Exports as both `useClipboard` and its alias `useCliphook` to avoid naming collisions with other hooks.
+- **Headless Component**: Provide ultimate UI flexibility with the `CopyToClipboard` component.
+- **Bonus `useLocalStorage`**: Includes a type-safe, SSR-safe hook with cross-tab synchronization.
+
+## 🚀 Installation
+
+```bash
+npm install cliphook
+# or
+yarn add cliphook
+# or
+pnpm add cliphook
+```
+
+## 📋 Quick Start
+
+### 1. Hook Usage (`useCliphook`)
+
+The easiest way to copy text inside your components.
+
+```tsx
+import { useCliphook } from 'cliphook';
+
+function MyComponent() {
+  const { copyText, isCopied } = useCliphook({ timeout: 2000 });
+
+  return (
+    <button onClick={() => copyText('Hello World!')}>
+      {isCopied ? '✅ Copied' : '📋 Copy to Clipboard'}
+    </button>
+  );
+}
+```
+
+### 2. Component Usage (`CopyToClipboard`)
+
+A headless wrapper that makes it easy to add copy functionality to any custom UI.
+
+```tsx
+import { CopyToClipboard } from 'cliphook';
+
+function MyButton() {
+  return (
+    <CopyToClipboard text="Some important text">
+      {({ copy, isCopied }) => (
+        <button onClick={copy}>
+          {isCopied ? 'Done!' : 'Copy'}
+        </button>
+      )}
+    </CopyToClipboard>
+  );
+}
+```
+
+### 3. Bonus Hook (`useLocalStorage`)
+
+Persist state automatically with cross-tab sync and SSR safety.
+
+```tsx
+import { useLocalStorage } from 'cliphook';
+
+function ThemeToggle() {
+  const [theme, setTheme] = useLocalStorage('theme', 'light');
+
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      Mode: {theme}
+    </button>
+  );
+}
+```
+
+## 📖 For More Detailed Examples
+Check out the **[EXAMPLES.md](./EXAMPLES.md)** file for advanced usage, types, and troubleshooting.
+
+## 📄 License
+MIT © satishjaiswal

package/dist/index.d.mts

@@ -0,0 +1,86 @@
+import React from 'react';
+
+interface ClipboardOptions {
+    /**
+     * Reset 'isCopied' state after this duration (ms).
+     * @default 2000
+     */
+    timeout?: number;
+}
+interface UseClipboardReturn {
+    /**
+     * Function to copy text to clipboard.
+     * @param text The string to copy.
+     */
+    copyText: (text: string) => Promise<void>;
+    /**
+     * Whether the last copy operation was successful.
+     */
+    isCopied: boolean;
+    /**
+     * Error object if the last copy operation failed.
+     */
+    error: Error | null;
+    /**
+     * Number of successful copy operations in this session.
+     */
+    copyCount: number;
+    /**
+     * Resets the 'isCopied' and 'error' state manually.
+     */
+    reset: () => void;
+}
+/**
+ * useClipboard is a React hook that makes copying text to the clipboard effortless.
+ *
+ * @alias useCliphook
+ */
+declare function useClipboard(options?: ClipboardOptions): UseClipboardReturn;
+/**
+ * Alias for useClipboard to avoid naming conflicts.
+ */
+declare const useCliphook: typeof useClipboard;
+
+interface CopyToClipboardProps extends ClipboardOptions {
+    /**
+     * The text to copy to the clipboard.
+     */
+    text: string;
+    /**
+     * A function that returns a React element.
+     * Receives the clipboard state (copy, isCopied, error, etc.) as an argument.
+     */
+    children: (props: UseClipboardReturn & {
+        copy: () => void;
+    }) => React.ReactNode;
+    /**
+     * Callback when copy is successful.
+     */
+    onCopy?: (text: string) => void;
+    /**
+     * Callback when copy fails.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * CopyToClipboard is a headless component that makes copying text to the clipboard effortless.
+ *
+ * Example usage:
+ * ```tsx
+ * <CopyToClipboard text="Hello World">
+ *  {({ copy, isCopied }) => (
+ *   <button onClick={copy}>{isCopied ? 'Done!' : 'Copy'}</button>
+ * )}
+ * </CopyToClipboard>
+ * ```
+ */
+declare const CopyToClipboard: React.FC<CopyToClipboardProps>;
+
+/**
+ * useLocalStorage is a React hook that makes persisting state to localStorage effortless.
+ * Includes cross-tab synchronization and type safety.
+ * SSR safe: Does not cause hydration errors.
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((val: T) => T)) => void, () => void];
+
+export { type ClipboardOptions, CopyToClipboard, type CopyToClipboardProps, type UseClipboardReturn, useClipboard, useCliphook, useLocalStorage };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import React from 'react';
+
+interface ClipboardOptions {
+    /**
+     * Reset 'isCopied' state after this duration (ms).
+     * @default 2000
+     */
+    timeout?: number;
+}
+interface UseClipboardReturn {
+    /**
+     * Function to copy text to clipboard.
+     * @param text The string to copy.
+     */
+    copyText: (text: string) => Promise<void>;
+    /**
+     * Whether the last copy operation was successful.
+     */
+    isCopied: boolean;
+    /**
+     * Error object if the last copy operation failed.
+     */
+    error: Error | null;
+    /**
+     * Number of successful copy operations in this session.
+     */
+    copyCount: number;
+    /**
+     * Resets the 'isCopied' and 'error' state manually.
+     */
+    reset: () => void;
+}
+/**
+ * useClipboard is a React hook that makes copying text to the clipboard effortless.
+ *
+ * @alias useCliphook
+ */
+declare function useClipboard(options?: ClipboardOptions): UseClipboardReturn;
+/**
+ * Alias for useClipboard to avoid naming conflicts.
+ */
+declare const useCliphook: typeof useClipboard;
+
+interface CopyToClipboardProps extends ClipboardOptions {
+    /**
+     * The text to copy to the clipboard.
+     */
+    text: string;
+    /**
+     * A function that returns a React element.
+     * Receives the clipboard state (copy, isCopied, error, etc.) as an argument.
+     */
+    children: (props: UseClipboardReturn & {
+        copy: () => void;
+    }) => React.ReactNode;
+    /**
+     * Callback when copy is successful.
+     */
+    onCopy?: (text: string) => void;
+    /**
+     * Callback when copy fails.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * CopyToClipboard is a headless component that makes copying text to the clipboard effortless.
+ *
+ * Example usage:
+ * ```tsx
+ * <CopyToClipboard text="Hello World">
+ *  {({ copy, isCopied }) => (
+ *   <button onClick={copy}>{isCopied ? 'Done!' : 'Copy'}</button>
+ * )}
+ * </CopyToClipboard>
+ * ```
+ */
+declare const CopyToClipboard: React.FC<CopyToClipboardProps>;
+
+/**
+ * useLocalStorage is a React hook that makes persisting state to localStorage effortless.
+ * Includes cross-tab synchronization and type safety.
+ * SSR safe: Does not cause hydration errors.
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((val: T) => T)) => void, () => void];
+
+export { type ClipboardOptions, CopyToClipboard, type CopyToClipboardProps, type UseClipboardReturn, useClipboard, useCliphook, useLocalStorage };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var y=Object.create;var m=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var x=Object.getPrototypeOf,S=Object.prototype.hasOwnProperty;var h=(e,o)=>{for(var r in o)m(e,r,{get:o[r],enumerable:!0})},g=(e,o,r,n)=>{if(o&&typeof o=="object"||typeof o=="function")for(let c of E(o))!S.call(e,c)&&c!==r&&m(e,c,{get:()=>o[c],enumerable:!(n=T(o,c))||n.enumerable});return e};var R=(e,o,r)=>(r=e!=null?y(x(e)):{},g(o||!e||!e.__esModule?m(r,"default",{value:e,enumerable:!0}):r,e)),O=e=>g(m({},"__esModule",{value:!0}),e);var N={};h(N,{CopyToClipboard:()=>I,useClipboard:()=>w,useCliphook:()=>F,useLocalStorage:()=>U});module.exports=O(N);var i=require("react");function L(e){let o=document.createElement("textarea");o.value=e,o.style.position="fixed",o.style.left="-9999px",o.style.top="0",document.body.appendChild(o),o.focus(),o.select();try{let r=document.execCommand("copy");return document.body.removeChild(o),r}catch{return document.body.removeChild(o),!1}}function w(e={}){let{timeout:o=2e3}=e,[r,n]=(0,i.useState)(!1),[c,l]=(0,i.useState)(null),[p,u]=(0,i.useState)(0),s=(0,i.useRef)(null),t=(0,i.useCallback)(()=>{n(!1),l(null),s.current&&clearTimeout(s.current)},[]),d=(0,i.useCallback)(async b=>{s.current&&clearTimeout(s.current);try{if(navigator?.clipboard?.writeText)await navigator.clipboard.writeText(b);else if(!L(b))throw new Error("Fallback clipboard copy failed");n(!0),l(null),u(f=>f+1),o>0&&(s.current=setTimeout(()=>{n(!1)},o))}catch(f){n(!1),l(f instanceof Error?f:new Error("Failed to copy to clipboard"))}},[o]);return(0,i.useEffect)(()=>()=>{s.current&&clearTimeout(s.current)},[]),{copyText:d,isCopied:r,error:c,copyCount:p,reset:t}}var F=w;var v=R(require("react"));var C=require("react/jsx-runtime"),I=({text:e,children:o,onCopy:r,onError:n,...c})=>{let{copyText:l,...p}=w(c),u=v.default.useCallback(async()=>{try{await l(e),r&&r(e)}catch(s){n&&s instanceof Error&&n(s)}},[l,e,r,n]);return(0,C.jsx)(C.Fragment,{children:o({...p,copyText:l,copy:u})})};var a=require("react");function U(e,o){let r=(0,a.useCallback)(()=>{if(typeof window>"u")return o;try{let t=window.localStorage.getItem(e);return t?JSON.parse(t):o}catch(t){return console.warn(`Error reading localStorage key "${e}":`,t),o}},[o,e]),[n,c]=(0,a.useState)(r),l=(0,a.useCallback)(t=>{try{let d=t instanceof Function?t(n):t;c(d),typeof window<"u"&&(window.localStorage.setItem(e,JSON.stringify(d)),window.dispatchEvent(new Event("local-storage")))}catch(d){console.warn(`Error setting localStorage key "${e}":`,d)}},[e,n]),p=(0,a.useCallback)(()=>{try{typeof window<"u"&&(window.localStorage.removeItem(e),c(o),window.dispatchEvent(new Event("local-storage")))}catch(t){console.warn(`Error removing localStorage key "${e}":`,t)}},[e,o]),u=(0,a.useCallback)(t=>{t.key&&t.key!==e||c(r())},[e,r]);(0,a.useEffect)(()=>(window.addEventListener("storage",u),window.addEventListener("local-storage",u),()=>{window.removeEventListener("storage",u),window.removeEventListener("local-storage",u)}),[u]);let s=(0,a.useRef)(!0);return(0,a.useEffect)(()=>{if(s.current){s.current=!1;let t=r();t!==n&&c(t)}},[r,n]),[n,l,p]}0&&(module.exports={CopyToClipboard,useClipboard,useCliphook,useLocalStorage});

package/dist/index.mjs

@@ -0,0 +1 @@
+import{useState as f,useCallback as C,useRef as g,useEffect as v}from"react";function y(o){let e=document.createElement("textarea");e.value=o,e.style.position="fixed",e.style.left="-9999px",e.style.top="0",document.body.appendChild(e),e.focus(),e.select();try{let t=document.execCommand("copy");return document.body.removeChild(e),t}catch{return document.body.removeChild(e),!1}}function m(o={}){let{timeout:e=2e3}=o,[t,n]=f(!1),[i,s]=f(null),[u,a]=f(0),c=g(null),r=C(()=>{n(!1),s(null),c.current&&clearTimeout(c.current)},[]),l=C(async w=>{c.current&&clearTimeout(c.current);try{if(navigator?.clipboard?.writeText)await navigator.clipboard.writeText(w);else if(!y(w))throw new Error("Fallback clipboard copy failed");n(!0),s(null),a(d=>d+1),e>0&&(c.current=setTimeout(()=>{n(!1)},e))}catch(d){n(!1),s(d instanceof Error?d:new Error("Failed to copy to clipboard"))}},[e]);return v(()=>()=>{c.current&&clearTimeout(c.current)},[]),{copyText:l,isCopied:t,error:i,copyCount:u,reset:r}}var O=m;import T from"react";import{Fragment as E,jsx as x}from"react/jsx-runtime";var P=({text:o,children:e,onCopy:t,onError:n,...i})=>{let{copyText:s,...u}=m(i),a=T.useCallback(async()=>{try{await s(o),t&&t(o)}catch(c){n&&c instanceof Error&&n(c)}},[s,o,t,n]);return x(E,{children:e({...u,copyText:s,copy:a})})};import{useState as S,useCallback as p,useEffect as b,useRef as h}from"react";function A(o,e){let t=p(()=>{if(typeof window>"u")return e;try{let r=window.localStorage.getItem(o);return r?JSON.parse(r):e}catch(r){return console.warn(`Error reading localStorage key "${o}":`,r),e}},[e,o]),[n,i]=S(t),s=p(r=>{try{let l=r instanceof Function?r(n):r;i(l),typeof window<"u"&&(window.localStorage.setItem(o,JSON.stringify(l)),window.dispatchEvent(new Event("local-storage")))}catch(l){console.warn(`Error setting localStorage key "${o}":`,l)}},[o,n]),u=p(()=>{try{typeof window<"u"&&(window.localStorage.removeItem(o),i(e),window.dispatchEvent(new Event("local-storage")))}catch(r){console.warn(`Error removing localStorage key "${o}":`,r)}},[o,e]),a=p(r=>{r.key&&r.key!==o||i(t())},[o,t]);b(()=>(window.addEventListener("storage",a),window.addEventListener("local-storage",a),()=>{window.removeEventListener("storage",a),window.removeEventListener("local-storage",a)}),[a]);let c=h(!0);return b(()=>{if(c.current){c.current=!1;let r=t();r!==n&&i(r)}},[t,n]),[n,s,u]}export{P as CopyToClipboard,m as useClipboard,O as useCliphook,A as useLocalStorage};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "cliphook",
+  "version": "0.1.0",
+  "description": "A lightweight, developer-friendly React hook + component for easy clipboard management with built-in feedback states.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --minify",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "lint": "tsc"
+  },
+  "keywords": [
+    "react",
+    "hook",
+    "clipboard",
+    "copy",
+    "copy-to-clipboard",
+    "useClipboard",
+    "useCliphook"
+  ],
+  "author": "satishjaiswal",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}