@kikiutils/shared 9.0.0 → 9.2.0

package/dist/url.mjs

@@ -0,0 +1,19 @@
+/**
+ * Appends or updates the `redirect` query parameter on a given URL.
+ *
+ * Typically used to preserve the user's current path for post-login navigation.
+ *
+ * @param {string} url - The target URL to modify.
+ * @param {string} redirectPath - The path to use as the redirect destination.
+ *
+ * @returns {string} A new URL string with the `redirect` query parameter.
+ */
+function appendRedirectParamToUrl(url, redirectPath) {
+    const [base, rawQuery = ''] = url.split('?');
+    const searchParams = new URLSearchParams(rawQuery);
+    searchParams.set('redirect', redirectPath);
+    return `${base}?${searchParams.toString()}`;
+}
+
+export { appendRedirectParamToUrl };
+//# sourceMappingURL=url.mjs.map

package/dist/url.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.mjs","sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param {string} url - The target URL to modify.\n * @param {string} redirectPath - The path to use as the redirect destination.\n *\n * @returns {string} A new URL string with the `redirect` query parameter.\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    const [base, rawQuery = ''] = url.split('?');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    return `${base}?${searchParams.toString()}`;\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;AASG;AACa,SAAA,wBAAwB,CAAC,GAAW,EAAE,YAAoB,EAAA;AACtE,IAAA,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;AAC5C,IAAA,MAAM,YAAY,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC;AAClD,IAAA,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC;IAC1C,OAAO,CAAA,EAAG,IAAI,CAAI,CAAA,EAAA,YAAY,CAAC,QAAQ,EAAE,EAAE;AAC/C;;;;"}

package/dist/vue.cjs

@@ -0,0 +1,64 @@
+'use strict';
+
+const vue = require('vue');
+const vueRouter = require('vue-router');
+const url = require('./url.cjs');
+
+/**
+ * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current route fullPath as the `redirect` parameter.
+ */
+function appendRedirectParamFromCurrentRouteToUrl(url$1) {
+    return url.appendRedirectParamToUrl(url$1, vueRouter.useRoute().fullPath);
+}
+/**
+ * Clears an interval referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+function clearIntervalRef(intervalRef) {
+    if (intervalRef.value)
+        clearInterval(intervalRef.value);
+    intervalRef.value = null;
+}
+/**
+ * Clears a timeout referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+function clearTimeoutRef(timeoutRef) {
+    if (timeoutRef.value)
+        clearTimeout(timeoutRef.value);
+    timeoutRef.value = null;
+}
+/**
+ * A Vue composition function that remembers and restores scroll position
+ * of a scrollable container across route changes and keep-alive activation.
+ *
+ * @template T - The type of the scrollable element (defaults to HTMLElement).
+ *
+ * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element.
+ */
+function usePreserveScroll(containerRef) {
+    let scrollLeft = 0;
+    let scrollTop = 0;
+    vue.onActivated(() => {
+        if (!containerRef.value)
+            return;
+        containerRef.value.scrollLeft = scrollLeft;
+        containerRef.value.scrollTop = scrollTop;
+    });
+    vueRouter.onBeforeRouteLeave(() => {
+        scrollLeft = containerRef.value?.scrollLeft || 0;
+        scrollTop = containerRef.value?.scrollTop || 0;
+    });
+}
+
+exports.appendRedirectParamFromCurrentRouteToUrl = appendRedirectParamFromCurrentRouteToUrl;
+exports.clearIntervalRef = clearIntervalRef;
+exports.clearTimeoutRef = clearTimeoutRef;
+exports.usePreserveScroll = usePreserveScroll;
+//# sourceMappingURL=vue.cjs.map

package/dist/vue.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.cjs","sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify.\n *\n * @returns {string} A new URL with the current route fullPath as the `redirect` parameter.\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null.\n */\nexport function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null.\n */\nexport function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * A Vue composition function that remembers and restores scroll position\n * of a scrollable container across route changes and keep-alive activation.\n *\n * @template T - The type of the scrollable element (defaults to HTMLElement).\n *\n * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element.\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"names":["url","appendRedirectParamToUrl","useRoute","onActivated","onBeforeRouteLeave"],"mappings":";;;;;;AASA;;;;;;AAMG;AACG,SAAU,wCAAwC,CAACA,KAAW,EAAA;IAChE,OAAOC,4BAAwB,CAACD,KAAG,EAAEE,kBAAQ,EAAE,CAAC,QAAQ,CAAC;AAC7D;AAEA;;;;AAIG;AACG,SAAU,gBAAgB,CAAC,WAAuD,EAAA;IACpF,IAAI,WAAW,CAAC,KAAK;AAAE,QAAA,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC;AACvD,IAAA,WAAW,CAAC,KAAK,GAAG,IAAI;AAC5B;AAEA;;;;AAIG;AACG,SAAU,eAAe,CAAC,UAAqD,EAAA;IACjF,IAAI,UAAU,CAAC,KAAK;AAAE,QAAA,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC;AACpD,IAAA,UAAU,CAAC,KAAK,GAAG,IAAI;AAC3B;AAEA;;;;;;;AAOG;AACG,SAAU,iBAAiB,CAAkC,YAA2B,EAAA;IAC1F,IAAI,UAAU,GAAG,CAAC;IAClB,IAAI,SAAS,GAAG,CAAC;IACjBC,eAAW,CAAC,MAAK;QACb,IAAI,CAAC,YAAY,CAAC,KAAK;YAAE;AACzB,QAAA,YAAY,CAAC,KAAK,CAAC,UAAU,GAAG,UAAU;AAC1C,QAAA,YAAY,CAAC,KAAK,CAAC,SAAS,GAAG,SAAS;AAC5C,KAAC,CAAC;IAEFC,4BAAkB,CAAC,MAAK;QACpB,UAAU,GAAG,YAAY,CAAC,KAAK,EAAE,UAAU,IAAI,CAAC;QAChD,SAAS,GAAG,YAAY,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC;AAClD,KAAC,CAAC;AACN;;;;;;;"}

package/dist/vue.d.ts

@@ -0,0 +1,31 @@
+import type { Ref } from 'vue';
+/**
+ * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current route fullPath as the `redirect` parameter.
+ */
+export declare function appendRedirectParamFromCurrentRouteToUrl(url: string): string;
+/**
+ * Clears an interval referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+export declare function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>): void;
+/**
+ * Clears a timeout referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+export declare function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>): void;
+/**
+ * A Vue composition function that remembers and restores scroll position
+ * of a scrollable container across route changes and keep-alive activation.
+ *
+ * @template T - The type of the scrollable element (defaults to HTMLElement).
+ *
+ * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element.
+ */
+export declare function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>): void;
+//# sourceMappingURL=vue.d.ts.map

package/dist/vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.d.ts","sourceRoot":"","sources":["../src/vue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAQ/B;;;;;;GAMG;AACH,wBAAgB,wCAAwC,CAAC,GAAG,EAAE,MAAM,UAEnE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,QAGvF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,QAGpF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,EAAE,YAAY,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,QAa7F"}

package/dist/vue.mjs

@@ -0,0 +1,59 @@
+import { onActivated } from 'vue';
+import { useRoute, onBeforeRouteLeave } from 'vue-router';
+import { appendRedirectParamToUrl } from './url.mjs';
+
+/**
+ * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current route fullPath as the `redirect` parameter.
+ */
+function appendRedirectParamFromCurrentRouteToUrl(url) {
+    return appendRedirectParamToUrl(url, useRoute().fullPath);
+}
+/**
+ * Clears an interval referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+function clearIntervalRef(intervalRef) {
+    if (intervalRef.value)
+        clearInterval(intervalRef.value);
+    intervalRef.value = null;
+}
+/**
+ * Clears a timeout referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+function clearTimeoutRef(timeoutRef) {
+    if (timeoutRef.value)
+        clearTimeout(timeoutRef.value);
+    timeoutRef.value = null;
+}
+/**
+ * A Vue composition function that remembers and restores scroll position
+ * of a scrollable container across route changes and keep-alive activation.
+ *
+ * @template T - The type of the scrollable element (defaults to HTMLElement).
+ *
+ * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element.
+ */
+function usePreserveScroll(containerRef) {
+    let scrollLeft = 0;
+    let scrollTop = 0;
+    onActivated(() => {
+        if (!containerRef.value)
+            return;
+        containerRef.value.scrollLeft = scrollLeft;
+        containerRef.value.scrollTop = scrollTop;
+    });
+    onBeforeRouteLeave(() => {
+        scrollLeft = containerRef.value?.scrollLeft || 0;
+        scrollTop = containerRef.value?.scrollTop || 0;
+    });
+}
+
+export { appendRedirectParamFromCurrentRouteToUrl, clearIntervalRef, clearTimeoutRef, usePreserveScroll };
+//# sourceMappingURL=vue.mjs.map

package/dist/vue.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.mjs","sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify.\n *\n * @returns {string} A new URL with the current route fullPath as the `redirect` parameter.\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null.\n */\nexport function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null.\n */\nexport function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * A Vue composition function that remembers and restores scroll position\n * of a scrollable container across route changes and keep-alive activation.\n *\n * @template T - The type of the scrollable element (defaults to HTMLElement).\n *\n * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element.\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"names":[],"mappings":";;;;AASA;;;;;;AAMG;AACG,SAAU,wCAAwC,CAAC,GAAW,EAAA;IAChE,OAAO,wBAAwB,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,QAAQ,CAAC;AAC7D;AAEA;;;;AAIG;AACG,SAAU,gBAAgB,CAAC,WAAuD,EAAA;IACpF,IAAI,WAAW,CAAC,KAAK;AAAE,QAAA,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC;AACvD,IAAA,WAAW,CAAC,KAAK,GAAG,IAAI;AAC5B;AAEA;;;;AAIG;AACG,SAAU,eAAe,CAAC,UAAqD,EAAA;IACjF,IAAI,UAAU,CAAC,KAAK;AAAE,QAAA,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC;AACpD,IAAA,UAAU,CAAC,KAAK,GAAG,IAAI;AAC3B;AAEA;;;;;;;AAOG;AACG,SAAU,iBAAiB,CAAkC,YAA2B,EAAA;IAC1F,IAAI,UAAU,GAAG,CAAC;IAClB,IAAI,SAAS,GAAG,CAAC;IACjB,WAAW,CAAC,MAAK;QACb,IAAI,CAAC,YAAY,CAAC,KAAK;YAAE;AACzB,QAAA,YAAY,CAAC,KAAK,CAAC,UAAU,GAAG,UAAU;AAC1C,QAAA,YAAY,CAAC,KAAK,CAAC,SAAS,GAAG,SAAS;AAC5C,KAAC,CAAC;IAEF,kBAAkB,CAAC,MAAK;QACpB,UAAU,GAAG,YAAY,CAAC,KAAK,EAAE,UAAU,IAAI,CAAC;QAChD,SAAS,GAAG,YAAY,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC;AAClD,KAAC,CAAC;AACN;;;;"}

package/dist/web.cjs

@@ -0,0 +1,18 @@
+'use strict';
+
+const url = require('./url.cjs');
+
+/**
+ * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current location as the `redirect` parameter.
+ */
+function appendRedirectParamFromCurrentLocationToUrl(url$1) {
+    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+    return url.appendRedirectParamToUrl(url$1, currentPath);
+}
+
+exports.appendRedirectParamFromCurrentLocationToUrl = appendRedirectParamFromCurrentLocationToUrl;
+//# sourceMappingURL=web.cjs.map

package/dist/web.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.cjs","sources":["../src/web.ts"],"sourcesContent":["import { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify.\n *\n * @returns {string} A new URL with the current location as the `redirect` parameter.\n */\nexport function appendRedirectParamFromCurrentLocationToUrl(url: string) {\n    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;\n    return appendRedirectParamToUrl(url, currentPath);\n}\n"],"names":["url","appendRedirectParamToUrl"],"mappings":";;;;AAEA;;;;;;AAMG;AACG,SAAU,2CAA2C,CAACA,KAAW,EAAA;IACnE,MAAM,WAAW,GAAG,CAAG,EAAA,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAG,EAAA,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAG,EAAA,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA,CAAE;AACjG,IAAA,OAAOC,4BAAwB,CAACD,KAAG,EAAE,WAAW,CAAC;AACrD;;;;"}

package/dist/web.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current location as the `redirect` parameter.
+ */
+export declare function appendRedirectParamFromCurrentLocationToUrl(url: string): string;
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,2CAA2C,CAAC,GAAG,EAAE,MAAM,UAGtE"}

package/dist/web.mjs

@@ -0,0 +1,16 @@
+import { appendRedirectParamToUrl } from './url.mjs';
+
+/**
+ * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current location as the `redirect` parameter.
+ */
+function appendRedirectParamFromCurrentLocationToUrl(url) {
+    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+    return appendRedirectParamToUrl(url, currentPath);
+}
+
+export { appendRedirectParamFromCurrentLocationToUrl };
+//# sourceMappingURL=web.mjs.map

package/dist/web.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.mjs","sources":["../src/web.ts"],"sourcesContent":["import { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify.\n *\n * @returns {string} A new URL with the current location as the `redirect` parameter.\n */\nexport function appendRedirectParamFromCurrentLocationToUrl(url: string) {\n    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;\n    return appendRedirectParamToUrl(url, currentPath);\n}\n"],"names":[],"mappings":";;AAEA;;;;;;AAMG;AACG,SAAU,2CAA2C,CAAC,GAAW,EAAA;IACnE,MAAM,WAAW,GAAG,CAAG,EAAA,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAG,EAAA,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAG,EAAA,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA,CAAE;AACjG,IAAA,OAAO,wBAAwB,CAAC,GAAG,EAAE,WAAW,CAAC;AACrD;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kikiutils/shared",
-  "version": "9.0.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",
@@ -66,12 +66,15 @@
     "date-fns": "^4.1.0",
     "decimal.js": "^10.5.0",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "millify": "^6.1.0",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
     "ts-jest": "^29.3.2",
     "ts-project-builder": "5.0.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vue": "^3.5.13",
+    "vue-router": "^4.5.1"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

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,
+        };
+    }
+}

package/src/consola.ts

@@ -13,7 +13,7 @@ import { createConsola } from 'consola';
  *
  * @example
  * ```typescript
- * import logger from '@kikiutils/shared/consola';
+ * import { logger } from '@kikiutils/shared/consola';
  *
  * logger.info('test'); // ℹ test 3:56:30 AM
  *

package/src/crypto-hash.ts

@@ -2,6 +2,7 @@
  * This file provides a set of functions for creating hash digests using different algorithms and bit lengths.
  * It includes functions for generating SHA-3 hash digests with bit lengths of 224, 256, 384, and 512,
  * as well as a function for generating MD5 hash digests.
+ *
  * These functions use the Node.js crypto module to generate the hashes.
  * Can only be used in Node.js/Deno/Bun runtimes.
  *

package/src/datetime.ts

@@ -26,6 +26,7 @@ export type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek'
  * @param {DateArg<Date>} date - The input date to format. Can be a Date object, a timestamp, or a string.
  * @param {string} [format] - The target format string.
  * @param {FormatOptions} [options] - Optional formatting options passed to `date-fns/format`.
+ *
  * @returns {string} The formatted date string.
  *
  * @example
@@ -58,6 +59,7 @@ export function formatDate(date: DateArg<Date> & {}, format: string = 'yyyy-MM-d
  * @param {object} [options] - Optional settings.
  * @param {boolean} [options.setEndDateToNextDayStart] - If true, set `endDate` to 00:00:00.000 of the next day.
  * @param {Day} [options.weekStartsOn] - The start day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).
+ *
  * @returns {{ startDate: Date, endDate: Date }} An object with `startDate` and `endDate`.
  *
  * @example
@@ -135,6 +137,7 @@ export function getDateRangeFromDate(
  * Returns a `Date` object set to midnight (00:00:00) of today, with an optional day offset.
  *
  * @param {number} [offsetDays] - Number of days to offset from today. Can be negative.
+ *
  * @returns {Date} A `Date` object at 00:00:00 of the offset day.
  *
  * @example

package/src/enum.ts

@@ -3,6 +3,7 @@
  *
  * @param {Record<number | string, number | string>} data - The enumeration-like object to extract numeric values from.
  * The keys can be numbers or strings, and the values can be numbers or strings.
+ *
  * @returns {number[]} An array of numeric values extracted from the object.
  *
  * @example
@@ -27,6 +28,7 @@ export function getEnumNumberValues(data: Record<number | string, number | strin
  *
  * @param {Record<number | string, number | string>} data - The enumeration-like object to extract string values from.
  * The keys can be numbers or strings, and the values can be numbers or strings.
+ *
  * @returns {string[]} An array of string values extracted from the object.
  *
  * @example

package/src/env.ts

@@ -25,7 +25,9 @@ export class EnvironmentNotFoundError extends Error {
  * Retrieves the value of an environment variable, or throws an error if not set.
  *
  * @param {string} key - The environment variable key to check.
+ *
  * @returns {string} The value of the environment variable.
+ *
  * @throws {EnvironmentNotFoundError} If the environment variable is not defined.
  *
  * @example

package/src/general.ts

@@ -10,6 +10,7 @@
  *
  * @param {T | T[]} value - A single value or an array of values.
  * @param {D} [defaultValue] - A fallback value if the result is `null` or `undefined`.
+ *
  * @returns {T | D | undefined} The first value or the fallback.
  *
  * @example

package/src/math.ts

@@ -8,12 +8,14 @@ type CalculableValue = Decimal.Value | { toString: () => string };
 export interface ToPercentageStringOptions {
     /**
      * Number of decimal places to include in the result.
+     *
      * @default 2
      */
     decimalPlaces?: number;
 
     /**
      * Whether to include the '%' symbol in the result.
+     *
      * @default true
      */
     withSymbol?: boolean;
@@ -29,6 +31,7 @@ export interface ToPercentageStringOptions {
  * @param {CalculableValue} molecular - The numerator of the fraction.
  * @param {CalculableValue} denominator - The denominator of the fraction.
  * @param {ToPercentageStringOptions} [options] - Optional output settings.
+ *
  * @returns {string} Formatted percentage string.
  *
  * @example

package/src/number.ts

@@ -7,6 +7,7 @@ import { millify } from 'millify';
  *
  * @param {number} value - The number to format.
  * @param {Parameters<typeof millify>[1]} [options] - Optional configuration passed to `millify`.
+ *
  * @returns {string} The compact number string.
  *
  * @example

package/src/pino.ts

@@ -23,7 +23,7 @@ const stream = PinoPretty({
  *
  * @example
  * ```typescript
- * import logger from '@kikiutils/shared/pino';
+ * import { logger } from '@kikiutils/shared/pino';
  *
  * logger.info('test'); // [2024-07-11 12:12:30.085] INFO: test
  *

package/src/random.ts

@@ -8,14 +8,15 @@
  *
  * This function supports any return type by using a generic type parameter.
  *
- * @typeParam T - The return type of the generator function.
+ * @template T - The return type of the generator function.
  *
- * @param generator - A function that accepts a length and returns a value of type T.
- * @param minMin - Lower bound of the first random range.
- * @param minMax - Upper bound of the first random range.
- * @param maxMin - Lower bound of the second random range.
- * @param maxMax - Upper bound of the second random range.
- * @returns The result of the generator function using the computed final length.
+ * @param {(length: number) => T} generator - A function that accepts a length and returns a value of type T.
+ * @param {number} minMin - Lower bound of the first random range.
+ * @param {number} minMax - Upper bound of the first random range.
+ * @param {number} maxMin - Lower bound of the second random range.
+ * @param {number} maxMax - Upper bound of the second random range.
+ *
+ * @returns {T} The result of the generator function using the computed final length.
  */
 export function generateWithNestedRandomLength<T = string>(
     generator: (length: number) => T,

package/src/string.ts

@@ -25,6 +25,7 @@ const CHARSETS: Record<RandomStringMode, string> = {
  *
  * @param {number} length - The length of the string to generate. Must be a positive integer.
  * @param {RandomStringMode} [mode] - The character set to use.
+ *
  * @returns {string} The generated random string.
  *
  * @throws {Error} If the length is not a positive integer or the mode is unsupported.

package/src/url.ts

@@ -0,0 +1,16 @@
+/**
+ * Appends or updates the `redirect` query parameter on a given URL.
+ *
+ * Typically used to preserve the user's current path for post-login navigation.
+ *
+ * @param {string} url - The target URL to modify.
+ * @param {string} redirectPath - The path to use as the redirect destination.
+ *
+ * @returns {string} A new URL string with the `redirect` query parameter.
+ */
+export function appendRedirectParamToUrl(url: string, redirectPath: string) {
+    const [base, rawQuery = ''] = url.split('?');
+    const searchParams = new URLSearchParams(rawQuery);
+    searchParams.set('redirect', redirectPath);
+    return `${base}?${searchParams.toString()}`;
+}

package/src/vue.ts

@@ -0,0 +1,62 @@
+import { onActivated } from 'vue';
+import type { Ref } from 'vue';
+import {
+    onBeforeRouteLeave,
+    useRoute,
+} from 'vue-router';
+
+import { appendRedirectParamToUrl } from './url';
+
+/**
+ * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current route fullPath as the `redirect` parameter.
+ */
+export function appendRedirectParamFromCurrentRouteToUrl(url: string) {
+    return appendRedirectParamToUrl(url, useRoute().fullPath);
+}
+
+/**
+ * Clears an interval referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+export function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>) {
+    if (intervalRef.value) clearInterval(intervalRef.value);
+    intervalRef.value = null;
+}
+
+/**
+ * Clears a timeout referenced by a Vue ref and sets it to null.
+ *
+ * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null.
+ */
+export function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>) {
+    if (timeoutRef.value) clearTimeout(timeoutRef.value);
+    timeoutRef.value = null;
+}
+
+/**
+ * A Vue composition function that remembers and restores scroll position
+ * of a scrollable container across route changes and keep-alive activation.
+ *
+ * @template T - The type of the scrollable element (defaults to HTMLElement).
+ *
+ * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element.
+ */
+export function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>) {
+    let scrollLeft = 0;
+    let scrollTop = 0;
+    onActivated(() => {
+        if (!containerRef.value) return;
+        containerRef.value.scrollLeft = scrollLeft;
+        containerRef.value.scrollTop = scrollTop;
+    });
+
+    onBeforeRouteLeave(() => {
+        scrollLeft = containerRef.value?.scrollLeft || 0;
+        scrollTop = containerRef.value?.scrollTop || 0;
+    });
+}

package/src/web.ts

@@ -0,0 +1,13 @@
+import { appendRedirectParamToUrl } from './url';
+
+/**
+ * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.
+ *
+ * @param {string} url - The base URL to modify.
+ *
+ * @returns {string} A new URL with the current location as the `redirect` parameter.
+ */
+export function appendRedirectParamFromCurrentLocationToUrl(url: string) {
+    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+    return appendRedirectParamToUrl(url, currentPath);
+}