@kikiutils/shared 9.1.0 → 9.2.0

package/README.md

@@ -11,6 +11,7 @@ A lightweight modular utility library for JavaScript and TypeScript, offering se
 
 ## Features
 
+- 📋 Clipboard utilities for copying text and blobs to the clipboard (Browser only)
 - 📜 Simple and flexible logging with Consola and Pino
 - 🔒 Secure hash utilities: MD5, SHA3-224/256/384/512
 - 📅 Datetime utilities for formatting, ranges, and offsets
@@ -20,7 +21,6 @@ A lightweight modular utility library for JavaScript and TypeScript, offering se
 - 💎 Number formatting (e.g. compact, currency, padding)
 - 🔤 String tools such as random string generation and casing helpers
 - 🌐 URL utilities for parsing and building query strings
-- 🖥️ Web utilities using DOM APIs (e.g. `scrollToTop`) (Browser only)
 - 🧩 Vue 3 utilities
 - ⚙️ General-purpose utilities like value extractors and type guards
 - 📦 Modular by design — import only what you need via `@kikiutils/shared/<module>`
@@ -68,7 +68,12 @@ Each module file includes function-level comments and usage examples.
 
 ### [consola](./src/consola.ts)
 
-- Console logger integration
+Console logger integration.
+
+### [clipboard](./src/clipboard.ts)
+
+- `copyBlobToClipboard`
+- `copyTextToClipboard`
 
 ### [crypto-hash](./src/crypto-hash.ts)
 
@@ -114,7 +119,7 @@ Each module file includes function-level comments and usage examples.
 
 ### [pino](./src/pino.ts)
 
-- Pino logger integration
+Pino logger integration.
 
 ### [random](./src/random.ts)
 

package/dist/clipboard.cjs

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * Attempts to copy a Blob (e.g. image, plain text, HTML) to the user's clipboard using the ClipboardItem API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in Safari and some older browsers.
+ *
+ * @param {Blob} blob - The Blob object to copy (e.g. from a File, image, or text content).
+ * @param {ClipboardItemOptions} [options] - Optional options passed to the ClipboardItem constructor.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const blob = new Blob(['Hello world'], { type: 'text/plain' });
+ * const result = await copyBlobToClipboard(blob);
+ * if (result.ok) {
+ *     console.log('Copied blob!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+async function copyBlobToClipboard(blob, options) {
+    if (!navigator.clipboard?.write) {
+        return {
+            error: new Error('Clipboard.write is not supported in this browser.'),
+            ok: false,
+        };
+    }
+    try {
+        const item = new ClipboardItem({ [blob.type]: blob }, options);
+        await navigator.clipboard.write([item]);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            error,
+            ok: false,
+        };
+    }
+}
+/**
+ * Attempts to copy the given text to the user's clipboard using the modern Clipboard API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in some older browsers (especially legacy Safari).
+ *
+ * @param {string} text - The string to be copied to the clipboard.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const result = await copyTextToClipboard('Hello!');
+ * if (result.ok) {
+ *     console.log('Copied!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+async function copyTextToClipboard(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            error,
+            ok: false,
+        };
+    }
+}
+
+exports.copyBlobToClipboard = copyBlobToClipboard;
+exports.copyTextToClipboard = copyTextToClipboard;
+//# sourceMappingURL=clipboard.cjs.map

package/dist/clipboard.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.cjs","sources":["../src/clipboard.ts"],"sourcesContent":["type CopyResult =\n  | { error: unknown; ok: false }\n  | { ok: true };\n\n/**\n * Attempts to copy a Blob (e.g. image, plain text, HTML) to the user's clipboard using the ClipboardItem API.\n *\n * ⚠️ Usage Notes:\n * - Must be called in a **secure context** (HTTPS or localhost).\n * - Must be called **in response to a user interaction** (e.g. click, input).\n * - Not supported in Safari and some older browsers.\n *\n * @param {Blob} blob - The Blob object to copy (e.g. from a File, image, or text content).\n * @param {ClipboardItemOptions} [options] - Optional options passed to the ClipboardItem constructor.\n *\n * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:\n *   - `{ ok: true }` if the copy succeeded\n *   - `{ ok: false, error }` if the copy failed, with the error included\n *\n * @example\n * ```typescript\n * const blob = new Blob(['Hello world'], { type: 'text/plain' });\n * const result = await copyBlobToClipboard(blob);\n * if (result.ok) {\n *     console.log('Copied blob!');\n * } else {\n *     console.error('Copy failed:', result.error);\n * }\n * ```\n */\nexport async function copyBlobToClipboard(blob: Blob, options?: ClipboardItemOptions): Promise<CopyResult> {\n    if (!navigator.clipboard?.write) {\n        return {\n            error: new Error('Clipboard.write is not supported in this browser.'),\n            ok: false,\n        };\n    }\n\n    try {\n        const item = new ClipboardItem({ [blob.type]: blob }, options);\n        await navigator.clipboard.write([item]);\n        return { ok: true };\n    } catch (error) {\n        return {\n            error,\n            ok: false,\n        };\n    }\n}\n\n/**\n * Attempts to copy the given text to the user's clipboard using the modern Clipboard API.\n *\n * ⚠️ Usage Notes:\n * - Must be called in a **secure context** (HTTPS or localhost).\n * - Must be called **in response to a user interaction** (e.g. click, input).\n * - Not supported in some older browsers (especially legacy Safari).\n *\n * @param {string} text - The string to be copied to the clipboard.\n *\n * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:\n *   - `{ ok: true }` if the copy succeeded\n *   - `{ ok: false, error }` if the copy failed, with the error included\n *\n * @example\n * ```typescript\n * const result = await copyTextToClipboard('Hello!');\n * if (result.ok) {\n *     console.log('Copied!');\n * } else {\n *     console.error('Copy failed:', result.error);\n * }\n * ```\n */\nexport async function copyTextToClipboard(text: string): Promise<CopyResult> {\n    try {\n        await navigator.clipboard.writeText(text);\n        return { ok: true };\n    } catch (error) {\n        return {\n            error,\n            ok: false,\n        };\n    }\n}\n"],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,eAAe,mBAAmB,CAAC,IAAU,EAAE,OAA8B,EAAA;AAChF,IAAA,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,KAAK,EAAE;QAC7B,OAAO;AACH,YAAA,KAAK,EAAE,IAAI,KAAK,CAAC,mDAAmD,CAAC;AACrE,YAAA,EAAE,EAAE,KAAK;SACZ;;AAGL,IAAA,IAAI;AACA,QAAA,MAAM,IAAI,GAAG,IAAI,aAAa,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,EAAE,OAAO,CAAC;QAC9D,MAAM,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;AACvC,QAAA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE;;IACrB,OAAO,KAAK,EAAE;QACZ,OAAO;YACH,KAAK;AACL,YAAA,EAAE,EAAE,KAAK;SACZ;;AAET;AAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACI,eAAe,mBAAmB,CAAC,IAAY,EAAA;AAClD,IAAA,IAAI;QACA,MAAM,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC;AACzC,QAAA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE;;IACrB,OAAO,KAAK,EAAE;QACZ,OAAO;YACH,KAAK;AACL,YAAA,EAAE,EAAE,KAAK;SACZ;;AAET;;;;;"}

package/dist/clipboard.d.ts

@@ -0,0 +1,60 @@
+type CopyResult = {
+    error: unknown;
+    ok: false;
+} | {
+    ok: true;
+};
+/**
+ * Attempts to copy a Blob (e.g. image, plain text, HTML) to the user's clipboard using the ClipboardItem API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in Safari and some older browsers.
+ *
+ * @param {Blob} blob - The Blob object to copy (e.g. from a File, image, or text content).
+ * @param {ClipboardItemOptions} [options] - Optional options passed to the ClipboardItem constructor.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const blob = new Blob(['Hello world'], { type: 'text/plain' });
+ * const result = await copyBlobToClipboard(blob);
+ * if (result.ok) {
+ *     console.log('Copied blob!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+export declare function copyBlobToClipboard(blob: Blob, options?: ClipboardItemOptions): Promise<CopyResult>;
+/**
+ * Attempts to copy the given text to the user's clipboard using the modern Clipboard API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in some older browsers (especially legacy Safari).
+ *
+ * @param {string} text - The string to be copied to the clipboard.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const result = await copyTextToClipboard('Hello!');
+ * if (result.ok) {
+ *     console.log('Copied!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+export declare function copyTextToClipboard(text: string): Promise<CopyResult>;
+export {};
+//# sourceMappingURL=clipboard.d.ts.map

package/dist/clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../src/clipboard.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GACX;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,KAAK,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBzG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAU3E"}

package/dist/clipboard.mjs

@@ -0,0 +1,84 @@
+/**
+ * Attempts to copy a Blob (e.g. image, plain text, HTML) to the user's clipboard using the ClipboardItem API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in Safari and some older browsers.
+ *
+ * @param {Blob} blob - The Blob object to copy (e.g. from a File, image, or text content).
+ * @param {ClipboardItemOptions} [options] - Optional options passed to the ClipboardItem constructor.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const blob = new Blob(['Hello world'], { type: 'text/plain' });
+ * const result = await copyBlobToClipboard(blob);
+ * if (result.ok) {
+ *     console.log('Copied blob!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+async function copyBlobToClipboard(blob, options) {
+    if (!navigator.clipboard?.write) {
+        return {
+            error: new Error('Clipboard.write is not supported in this browser.'),
+            ok: false,
+        };
+    }
+    try {
+        const item = new ClipboardItem({ [blob.type]: blob }, options);
+        await navigator.clipboard.write([item]);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            error,
+            ok: false,
+        };
+    }
+}
+/**
+ * Attempts to copy the given text to the user's clipboard using the modern Clipboard API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in some older browsers (especially legacy Safari).
+ *
+ * @param {string} text - The string to be copied to the clipboard.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const result = await copyTextToClipboard('Hello!');
+ * if (result.ok) {
+ *     console.log('Copied!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+async function copyTextToClipboard(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            error,
+            ok: false,
+        };
+    }
+}
+
+export { copyBlobToClipboard, copyTextToClipboard };
+//# sourceMappingURL=clipboard.mjs.map

package/dist/clipboard.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.mjs","sources":["../src/clipboard.ts"],"sourcesContent":["type CopyResult =\n  | { error: unknown; ok: false }\n  | { ok: true };\n\n/**\n * Attempts to copy a Blob (e.g. image, plain text, HTML) to the user's clipboard using the ClipboardItem API.\n *\n * ⚠️ Usage Notes:\n * - Must be called in a **secure context** (HTTPS or localhost).\n * - Must be called **in response to a user interaction** (e.g. click, input).\n * - Not supported in Safari and some older browsers.\n *\n * @param {Blob} blob - The Blob object to copy (e.g. from a File, image, or text content).\n * @param {ClipboardItemOptions} [options] - Optional options passed to the ClipboardItem constructor.\n *\n * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:\n *   - `{ ok: true }` if the copy succeeded\n *   - `{ ok: false, error }` if the copy failed, with the error included\n *\n * @example\n * ```typescript\n * const blob = new Blob(['Hello world'], { type: 'text/plain' });\n * const result = await copyBlobToClipboard(blob);\n * if (result.ok) {\n *     console.log('Copied blob!');\n * } else {\n *     console.error('Copy failed:', result.error);\n * }\n * ```\n */\nexport async function copyBlobToClipboard(blob: Blob, options?: ClipboardItemOptions): Promise<CopyResult> {\n    if (!navigator.clipboard?.write) {\n        return {\n            error: new Error('Clipboard.write is not supported in this browser.'),\n            ok: false,\n        };\n    }\n\n    try {\n        const item = new ClipboardItem({ [blob.type]: blob }, options);\n        await navigator.clipboard.write([item]);\n        return { ok: true };\n    } catch (error) {\n        return {\n            error,\n            ok: false,\n        };\n    }\n}\n\n/**\n * Attempts to copy the given text to the user's clipboard using the modern Clipboard API.\n *\n * ⚠️ Usage Notes:\n * - Must be called in a **secure context** (HTTPS or localhost).\n * - Must be called **in response to a user interaction** (e.g. click, input).\n * - Not supported in some older browsers (especially legacy Safari).\n *\n * @param {string} text - The string to be copied to the clipboard.\n *\n * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:\n *   - `{ ok: true }` if the copy succeeded\n *   - `{ ok: false, error }` if the copy failed, with the error included\n *\n * @example\n * ```typescript\n * const result = await copyTextToClipboard('Hello!');\n * if (result.ok) {\n *     console.log('Copied!');\n * } else {\n *     console.error('Copy failed:', result.error);\n * }\n * ```\n */\nexport async function copyTextToClipboard(text: string): Promise<CopyResult> {\n    try {\n        await navigator.clipboard.writeText(text);\n        return { ok: true };\n    } catch (error) {\n        return {\n            error,\n            ok: false,\n        };\n    }\n}\n"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,eAAe,mBAAmB,CAAC,IAAU,EAAE,OAA8B,EAAA;AAChF,IAAA,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,KAAK,EAAE;QAC7B,OAAO;AACH,YAAA,KAAK,EAAE,IAAI,KAAK,CAAC,mDAAmD,CAAC;AACrE,YAAA,EAAE,EAAE,KAAK;SACZ;;AAGL,IAAA,IAAI;AACA,QAAA,MAAM,IAAI,GAAG,IAAI,aAAa,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,EAAE,OAAO,CAAC;QAC9D,MAAM,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;AACvC,QAAA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE;;IACrB,OAAO,KAAK,EAAE;QACZ,OAAO;YACH,KAAK;AACL,YAAA,EAAE,EAAE,KAAK;SACZ;;AAET;AAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACI,eAAe,mBAAmB,CAAC,IAAY,EAAA;AAClD,IAAA,IAAI;QACA,MAAM,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC;AACzC,QAAA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE;;IACrB,OAAO,KAAK,EAAE;QACZ,OAAO;YACH,KAAK;AACL,YAAA,EAAE,EAAE,KAAK;SACZ;;AAET;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kikiutils/shared",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "A lightweight modular utility library for JavaScript and TypeScript, offering secure hashing, flexible logging, date utilities, Vue/web helpers, and more.",
   "author": "kiki-kanri",
   "license": "MIT",

package/src/clipboard.ts

@@ -0,0 +1,85 @@
+type CopyResult =
+  | { error: unknown; ok: false }
+  | { ok: true };
+
+/**
+ * Attempts to copy a Blob (e.g. image, plain text, HTML) to the user's clipboard using the ClipboardItem API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in Safari and some older browsers.
+ *
+ * @param {Blob} blob - The Blob object to copy (e.g. from a File, image, or text content).
+ * @param {ClipboardItemOptions} [options] - Optional options passed to the ClipboardItem constructor.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const blob = new Blob(['Hello world'], { type: 'text/plain' });
+ * const result = await copyBlobToClipboard(blob);
+ * if (result.ok) {
+ *     console.log('Copied blob!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+export async function copyBlobToClipboard(blob: Blob, options?: ClipboardItemOptions): Promise<CopyResult> {
+    if (!navigator.clipboard?.write) {
+        return {
+            error: new Error('Clipboard.write is not supported in this browser.'),
+            ok: false,
+        };
+    }
+
+    try {
+        const item = new ClipboardItem({ [blob.type]: blob }, options);
+        await navigator.clipboard.write([item]);
+        return { ok: true };
+    } catch (error) {
+        return {
+            error,
+            ok: false,
+        };
+    }
+}
+
+/**
+ * Attempts to copy the given text to the user's clipboard using the modern Clipboard API.
+ *
+ * ⚠️ Usage Notes:
+ * - Must be called in a **secure context** (HTTPS or localhost).
+ * - Must be called **in response to a user interaction** (e.g. click, input).
+ * - Not supported in some older browsers (especially legacy Safari).
+ *
+ * @param {string} text - The string to be copied to the clipboard.
+ *
+ * @returns {Promise<CopyResult>} A promise resolving to a `CopyResult`:
+ *   - `{ ok: true }` if the copy succeeded
+ *   - `{ ok: false, error }` if the copy failed, with the error included
+ *
+ * @example
+ * ```typescript
+ * const result = await copyTextToClipboard('Hello!');
+ * if (result.ok) {
+ *     console.log('Copied!');
+ * } else {
+ *     console.error('Copy failed:', result.error);
+ * }
+ * ```
+ */
+export async function copyTextToClipboard(text: string): Promise<CopyResult> {
+    try {
+        await navigator.clipboard.writeText(text);
+        return { ok: true };
+    } catch (error) {
+        return {
+            error,
+            ok: false,
+        };
+    }
+}