@gateweb/react-utils 1.16.0 → 2.0.0

package/dist/es/index.mjs

@@ -1,10 +1,87 @@
 import dayjs from 'dayjs';
-export { Q as QueryProvider, u as useQueryContext } from './queryStore-12s-CFQTVwrg.mjs';
-import React, { useMemo, createContext, useContext, useState, useCallback } from 'react';
-export { u as useCountdown } from './useCountdown-12s-t52WIHfq.mjs';
-export { u as useDisclosure } from './useDisclosure-12s-BQAHpAXK.mjs';
-export { d as downloadFile } from './download-12s-CnaJ0p_f.mjs';
-export { g as getLocalStorage, s as setLocalStorage } from './webStorage-12s-W1DItzhS.mjs';
+
+/* eslint-disable no-bitwise */ const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * 將位元組陣列編碼為 base64 字串
+ *
+ * @param bytes 要編碼的位元組陣列
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const bytes = new TextEncoder().encode('Hello World');
+ * const encoded = encodeBase64(bytes);
+ * console.log(encoded); // 'SGVsbG8gV29ybGQ='
+ * ```
+ */ const encodeBase64 = (bytes)=>{
+    let out = '';
+    for(let i = 0; i < bytes.length; i += 3){
+        const n = bytes[i] << 16 | (bytes[i + 1] || 0) << 8 | (bytes[i + 2] || 0);
+        out += chars[n >> 18 & 63] + chars[n >> 12 & 63] + (i + 1 < bytes.length ? chars[n >> 6 & 63] : '=') + (i + 2 < bytes.length ? chars[n & 63] : '=');
+    }
+    return out;
+};
+/**
+ * 將 base64 字串解碼為位元組陣列
+ *
+ * @param base64 要解碼的 base64 字串（支援 base64url 格式）
+ * @returns 解碼後的位元組陣列
+ *
+ * @example
+ * ```ts
+ * const decoded = decodeBase64('SGVsbG8gV29ybGQ=');
+ * const text = new TextDecoder().decode(decoded);
+ * console.log(text); // 'Hello World'
+ * ```
+ */ const decodeBase64 = (base64)=>{
+    let out = base64.replace(/-/g, '+').replace(/_/g, '/'); // 支援 base64url
+    while(out.length % 4)out += '='; // 自動補 "="
+    const buffer = [];
+    for(let i = 0; i < out.length; i += 4){
+        const n = chars.indexOf(out[i]) << 18 | chars.indexOf(out[i + 1]) << 12 | (chars.indexOf(out[i + 2]) & 63) << 6 | chars.indexOf(out[i + 3]) & 63;
+        buffer.push(n >> 16 & 255);
+        if (out[i + 2] !== '=') buffer.push(n >> 8 & 255);
+        if (out[i + 3] !== '=') buffer.push(n & 255);
+    }
+    return new Uint8Array(buffer);
+};
+/**
+ * 將 JSON 資料編碼為 base64 字串
+ *
+ * @param data 要編碼的 JSON 可序列化資料
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const data = { name: 'John', age: 30 };
+ * const encoded = encodeJson(data);
+ * console.log(encoded); // 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9'
+ *
+ * const array = [1, 2, 3];
+ * const encodedArray = encodeJson(array);
+ * ```
+ */ const encodeJson = (data)=>{
+    const json = JSON.stringify(data);
+    return encodeBase64(new TextEncoder().encode(json));
+};
+/**
+ * 將 base64 字串解碼為 JSON 資料
+ *
+ * @param b64 要解碼的 base64 字串
+ * @returns 解碼後的資料
+ *
+ * @example
+ * ```ts
+ * const encoded = 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9';
+ * const decoded = decodeJson<{ name: string; age: number }>(encoded);
+ * console.log(decoded); // { name: 'John', age: 30 }
+ *
+ * const decodedArray = decodeJson<number[]>(encodedArray);
+ * ```
+ */ const decodeJson = (b64)=>{
+    const json = new TextDecoder().decode(decodeBase64(b64));
+    return JSON.parse(json);
+};
 
 const FILE_SIZE_UNITS$1 = [
     'Bytes',
@@ -1239,100 +1316,6 @@ const FILE_SIZE_UNITS = [
  * }
  */ const isNil = (value)=>value === null || value === undefined;
 
-/**
- * Creates a strongly-typed React Context and Provider pair for data sharing.
- *
- * This utility helps you avoid prop drilling by providing a reusable way to define
- * context with strict type inference. It returns a custom hook for consuming the context
- * and a Provider component for supplying context values.
- *
- * @template T - The value type for the context.
- * @returns {object} An object containing:
- *   - useDataContext: A custom hook to access the context value. Throws an error if used outside the provider.
- *   - DataProvider: A Provider component to wrap your component tree and supply the context value.
- *
- * @example
- * // Example usage:
- * const { useDataContext, DataProvider } = createDataContext<{ count: number }>();
- *
- * function Counter() {
- *   const { count } = useDataContext();
- *   return <span>{count}</span>;
- * }
- *
- * function App() {
- *   return (
- *     <DataProvider value={{ count: 42 }}>
- *       <Counter />
- *     </DataProvider>
- *   );
- * }
- */ const createDataContext = ()=>{
-    const Context = /*#__PURE__*/ createContext(undefined);
-    const useDataContext = ()=>{
-        const context = useContext(Context);
-        if (context === undefined) {
-            throw new Error(`useDataContext must be used within a DataProvider`);
-        }
-        return context;
-    };
-    const DataProvider = ({ children, value })=>{
-        const memoized = useMemo(()=>value, [
-            value
-        ]);
-        return /*#__PURE__*/ React.createElement(Context.Provider, {
-            value: memoized
-        }, children);
-    };
-    return {
-        useDataContext,
-        DataProvider
-    };
-};
-
-/**
- * A hook to manage a value.
- *
- * @example
- *
- * ```tsx
- * const MyComponent = ({ value }: { value?: number }) => {
- *    const [currentValue, setCurrentValue] = useValue({ value });
- * };
- * ```
- */ const useValue = ({ value, defaultValue })=>{
-    if (value === undefined && defaultValue === undefined) {
-        throw new Error('Either `value` or `defaultValue` must be provided.');
-    }
-    const isControlled = value !== undefined;
-    const [internalValue, setInternalValue] = useState(defaultValue);
-    const setValue = useCallback((newValue)=>{
-        if (!isControlled) {
-            setInternalValue(newValue);
-        }
-    }, [
-        isControlled
-    ]);
-    const currentValue = isControlled ? value : internalValue;
-    return [
-        currentValue,
-        setValue
-    ];
-};
-
-function mergeRefs(refs) {
-    return (value)=>{
-        refs.forEach((ref)=>{
-            if (typeof ref === 'function') {
-                ref(value);
-            } else if (ref != null) {
-                // eslint-disable-next-line no-param-reassign
-                ref.current = value;
-            }
-        });
-    };
-}
-
 /**
  * 民國年轉西元年
  * @param dateString 日期字串
@@ -1414,4 +1397,4 @@ function mergeRefs(refs) {
     return dayjs(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-export { ByteSize, MimeTypeMap, OtherMimeType, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepClone, deepMerge, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNil, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeConfig, mergeRefs, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, renameKey, rocEraToAd, searchParamsToObject, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { ByteSize, MimeTypeMap, OtherMimeType, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createEnumLikeObject, debounce, decodeBase64, decodeJson, deepClone, deepMerge, encodeBase64, encodeJson, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNil, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeConfig, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, renameKey, rocEraToAd, searchParamsToObject, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, validTaxId, validateDateString, validateFileType, wait };

package/dist/es/{queryStore-12s-CFQTVwrg.mjs → queryStore-12s-Dkb-Af1n.mjs}

@@ -26,6 +26,8 @@ const createQueryStore = ({ query, handleChangeQuery })=>createStore()((set)=>({
 const QueryContext = /*#__PURE__*/ createContext(null);
 /**
  * Provider to provide the store to the context
+ *
+ * @deprecated use `StoreProvider` from `core/store` instead
  */ const QueryProvider = ({ children, query, handleChangeQuery })=>{
     const storeRef = useRef(null);
     if (!storeRef.current) {
@@ -57,6 +59,8 @@ const QueryContext = /*#__PURE__*/ createContext(null);
  * const result2 = useQueryContext<MyObject>()(q => q.changeQuery);
  * const result3 = useQueryContext<MyObject>()(q => q.query);
  * ```
+ *
+ * @deprecated use `useStoreContext` from `core/store` instead
  */ const useQueryContext = ()=>{
     const store = useContext(QueryContext);
     if (!store) throw new Error('Missing QueryContext.Provider in the tree');

package/dist/es/store-12s-DsXc3Uo0.mjs

@@ -0,0 +1,118 @@
+'use client';
+import React, { useContext, createContext, useRef } from 'react';
+import { createStore } from 'zustand';
+import { useStoreWithEqualityFn } from 'zustand/traditional';
+
+const isObject = (value)=>value !== null && typeof value === 'object';
+/**
+ * merge two objects deeply
+ *
+ * @param target - the target object
+ * @param source - the source object
+ *
+ * @example
+ *
+ * const obja = { a: { a1: { a11: 'value 1', a12: 'value 2' }, a2: 'value 3' }, b: 'value 4' };
+ * const objb = { a: { a1: { a13: 'value 5', a14: 'value 6' }, a3: 'value 7' }};
+ *
+ * const mergeResult = deepMerge(obja, objb); // { a: { a1: { a11: 'value 1', a12: 'value 2', a13: 'value 5', a14: 'value 6' }, a2: 'value 3', a3: 'value 7' }, b: 'value 4' }
+ *
+ */ const deepMerge = (target, source)=>Object.entries(source).reduce((acc, [key, value])=>{
+        if (isObject(value)) {
+            acc[key] = key in target && isObject(target[key]) ? deepMerge(target[key], value) : value;
+        } else {
+            acc[key] = value;
+        }
+        return acc;
+    }, {
+        ...target
+    });
+
+/**
+ * create a zustand store with changeStore method
+ */ const createZustandStore = ({ store, handleChangeStore, defaultMerge })=>createStore()((set)=>({
+            store,
+            changeStore: (updater, options)=>{
+                set((pre)=>{
+                    const patch = typeof updater === 'function' ? updater(pre.store) : updater;
+                    const newStore = handleChangeStore ? handleChangeStore(pre.store, patch) : patch;
+                    const strategy = options?.merge ?? defaultMerge;
+                    if (strategy === 'shallow') {
+                        return {
+                            store: {
+                                ...pre.store,
+                                ...newStore
+                            }
+                        };
+                    }
+                    return {
+                        store: deepMerge(pre.store, newStore)
+                    };
+                });
+            }
+        }));
+/**
+ * create a store context with provider and hooks
+ *
+ * @example
+ *
+ * ```tsx
+ * // create a store context
+ * const { StoreProvider, useStore, useStoreApi } = createStoreContext<MyObject>();
+ *
+ * // use the StoreProvider to provide the store to the context
+ * <StoreProvider store={{ key: 'value' }}>
+ *   <App />
+ * </StoreProvider>
+ * ```
+ */ const createStoreContext = ()=>{
+    const StoreContext = /*#__PURE__*/ createContext(null);
+    /**
+   * Provider to provide the store to the context
+   *
+   * @example
+   *
+   * ```tsx
+   * // use the StoreProvider to provide the store to the context
+   * const { StoreProvider } = createStoreContext<MyObject>();
+   *
+   * <StoreProvider store={{ key: 'value' }}>
+   *   <App />
+   * </StoreProvider>
+   * ```
+   */ const StoreProvider = ({ children, store = {}, handleChangeStore, defaultMerge = 'shallow' })=>{
+        const storeRef = useRef(null);
+        if (!storeRef.current) {
+            storeRef.current = createZustandStore({
+                store,
+                handleChangeStore,
+                defaultMerge
+            });
+        }
+        return /*#__PURE__*/ React.createElement(StoreContext.Provider, {
+            value: storeRef.current
+        }, children);
+    };
+    /**
+   * a hook to get the store from the context
+   *
+   * @example
+   * ```tsx
+   * const { useStore } = createStoreContext<MyObject>();
+   * const value = useStore(s => s.store);
+   * ```
+   *
+   * @param selector - the selector to get the state from the store
+   * @param equalityFn - the equality function to compare the previous and next state
+   */ const useStore = (selector, equalityFn)=>{
+        const store = useContext(StoreContext);
+        if (!store) throw new Error('Missing StoreContext.Provider in the tree');
+        return useStoreWithEqualityFn(store, selector, equalityFn);
+    };
+    return {
+        StoreProvider,
+        useStore
+    };
+};
+
+export { createStoreContext as c };

package/dist/es/webStorage-12s-Bo7x8q5t.mjs

@@ -0,0 +1,135 @@
+'use client';
+/* eslint-disable no-bitwise */ const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * 將位元組陣列編碼為 base64 字串
+ *
+ * @param bytes 要編碼的位元組陣列
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const bytes = new TextEncoder().encode('Hello World');
+ * const encoded = encodeBase64(bytes);
+ * console.log(encoded); // 'SGVsbG8gV29ybGQ='
+ * ```
+ */ const encodeBase64 = (bytes)=>{
+    let out = '';
+    for(let i = 0; i < bytes.length; i += 3){
+        const n = bytes[i] << 16 | (bytes[i + 1] || 0) << 8 | (bytes[i + 2] || 0);
+        out += chars[n >> 18 & 63] + chars[n >> 12 & 63] + (i + 1 < bytes.length ? chars[n >> 6 & 63] : '=') + (i + 2 < bytes.length ? chars[n & 63] : '=');
+    }
+    return out;
+};
+/**
+ * 將 base64 字串解碼為位元組陣列
+ *
+ * @param base64 要解碼的 base64 字串（支援 base64url 格式）
+ * @returns 解碼後的位元組陣列
+ *
+ * @example
+ * ```ts
+ * const decoded = decodeBase64('SGVsbG8gV29ybGQ=');
+ * const text = new TextDecoder().decode(decoded);
+ * console.log(text); // 'Hello World'
+ * ```
+ */ const decodeBase64 = (base64)=>{
+    let out = base64.replace(/-/g, '+').replace(/_/g, '/'); // 支援 base64url
+    while(out.length % 4)out += '='; // 自動補 "="
+    const buffer = [];
+    for(let i = 0; i < out.length; i += 4){
+        const n = chars.indexOf(out[i]) << 18 | chars.indexOf(out[i + 1]) << 12 | (chars.indexOf(out[i + 2]) & 63) << 6 | chars.indexOf(out[i + 3]) & 63;
+        buffer.push(n >> 16 & 255);
+        if (out[i + 2] !== '=') buffer.push(n >> 8 & 255);
+        if (out[i + 3] !== '=') buffer.push(n & 255);
+    }
+    return new Uint8Array(buffer);
+};
+/**
+ * 將 JSON 資料編碼為 base64 字串
+ *
+ * @param data 要編碼的 JSON 可序列化資料
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const data = { name: 'John', age: 30 };
+ * const encoded = encodeJson(data);
+ * console.log(encoded); // 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9'
+ *
+ * const array = [1, 2, 3];
+ * const encodedArray = encodeJson(array);
+ * ```
+ */ const encodeJson = (data)=>{
+    const json = JSON.stringify(data);
+    return encodeBase64(new TextEncoder().encode(json));
+};
+/**
+ * 將 base64 字串解碼為 JSON 資料
+ *
+ * @param b64 要解碼的 base64 字串
+ * @returns 解碼後的資料
+ *
+ * @example
+ * ```ts
+ * const encoded = 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9';
+ * const decoded = decodeJson<{ name: string; age: number }>(encoded);
+ * console.log(decoded); // { name: 'John', age: 30 }
+ *
+ * const decodedArray = decodeJson<number[]>(encodedArray);
+ * ```
+ */ const decodeJson = (b64)=>{
+    const json = new TextDecoder().decode(decodeBase64(b64));
+    return JSON.parse(json);
+};
+
+/**
+ * 從 localStorage 取得資料，支援槽狀取值(Json 物件)
+ *
+ * @param key 鍵值
+ * @param deCode 是否解碼
+ * @returns 取得的資料
+ * @example
+ * const data = getLocalStorage('key');
+ *
+ * const data = getLocalStorage('key.subKey');
+ */ const getLocalStorage = (key, deCode = true)=>{
+    const keys = key.split('.');
+    const storage = localStorage.getItem(keys[0]);
+    if (!storage) return undefined;
+    let currentObject;
+    try {
+        if (deCode) {
+            currentObject = decodeJson(storage);
+        } else {
+            currentObject = JSON.parse(storage);
+        }
+    } catch (_error) {
+        return undefined;
+    }
+    // let currentObject = JSON.parse(storage);
+    if (keys.length === 1) {
+        return currentObject;
+    }
+    keys.shift();
+    while(keys.length > 0){
+        const currentKey = keys.shift();
+        if (!currentKey) break;
+        currentObject = currentObject[currentKey];
+        if (!currentObject) break;
+    }
+    return currentObject;
+};
+/**
+ * 將資料(Json 物件)存入 localStorage
+ * @param key 鍵值
+ * @param value 可序列化的資料
+ * @param enCode 是否編碼
+ */ const setLocalStorage = (key, value, enCode = true)=>{
+    if (enCode) {
+        localStorage.setItem(key, encodeJson(value));
+    } else {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+};
+
+export { getLocalStorage as g, setLocalStorage as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "1.16.0",
+  "version": "2.0.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [
@@ -20,6 +20,16 @@
         "default": "./dist/cjs/index.js"
       }
     },
+    "./client": {
+      "import": {
+        "types": "./dist/es/client.d.mts",
+        "default": "./dist/es/client.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/client.d.ts",
+        "default": "./dist/cjs/client.js"
+      }
+    },
     "./types": {
       "import": {
         "types": "./dist/es/types.d.mts",

package/dist/cjs/webStorage-12s-DHr9PcPl.js

@@ -1,53 +0,0 @@
-'use client';
-/**
- * 從 localStorage 取得資料，支援槽狀取值
- *
- * @param key 鍵值
- * @param deCode 是否解碼
- * @returns 取得的資料
- * @example
- * const data = getLocalStorage('key');
- *
- * const data = getLocalStorage('key.subKey');
- */ const getLocalStorage = (key, deCode = true)=>{
-    const keys = key.split('.');
-    const storage = localStorage.getItem(keys[0]);
-    if (!storage) return undefined;
-    let currentObject;
-    try {
-        if (deCode) {
-            currentObject = JSON.parse(window.atob(storage));
-        } else {
-            currentObject = JSON.parse(storage);
-        }
-    } catch (_error) {
-        return undefined;
-    }
-    // let currentObject = JSON.parse(storage);
-    if (keys.length === 1) {
-        return currentObject;
-    }
-    keys.shift();
-    while(keys.length > 0){
-        const currentKey = keys.shift();
-        if (!currentKey) break;
-        currentObject = currentObject[currentKey];
-        if (!currentObject) break;
-    }
-    return currentObject;
-};
-/**
- * 將資料存入 localStorage
- * @param key 鍵值
- * @param value 可序列化的資料
- * @param enCode 是否編碼
- */ const setLocalStorage = (key, value, enCode = true)=>{
-    if (enCode) {
-        localStorage.setItem(key, window.btoa(JSON.stringify(value)));
-    } else {
-        localStorage.setItem(key, JSON.stringify(value));
-    }
-};
-
-exports.getLocalStorage = getLocalStorage;
-exports.setLocalStorage = setLocalStorage;

package/dist/es/webStorage-12s-W1DItzhS.mjs

@@ -1,52 +0,0 @@
-'use client';
-/**
- * 從 localStorage 取得資料，支援槽狀取值
- *
- * @param key 鍵值
- * @param deCode 是否解碼
- * @returns 取得的資料
- * @example
- * const data = getLocalStorage('key');
- *
- * const data = getLocalStorage('key.subKey');
- */ const getLocalStorage = (key, deCode = true)=>{
-    const keys = key.split('.');
-    const storage = localStorage.getItem(keys[0]);
-    if (!storage) return undefined;
-    let currentObject;
-    try {
-        if (deCode) {
-            currentObject = JSON.parse(window.atob(storage));
-        } else {
-            currentObject = JSON.parse(storage);
-        }
-    } catch (_error) {
-        return undefined;
-    }
-    // let currentObject = JSON.parse(storage);
-    if (keys.length === 1) {
-        return currentObject;
-    }
-    keys.shift();
-    while(keys.length > 0){
-        const currentKey = keys.shift();
-        if (!currentKey) break;
-        currentObject = currentObject[currentKey];
-        if (!currentObject) break;
-    }
-    return currentObject;
-};
-/**
- * 將資料存入 localStorage
- * @param key 鍵值
- * @param value 可序列化的資料
- * @param enCode 是否編碼
- */ const setLocalStorage = (key, value, enCode = true)=>{
-    if (enCode) {
-        localStorage.setItem(key, window.btoa(JSON.stringify(value)));
-    } else {
-        localStorage.setItem(key, JSON.stringify(value));
-    }
-};
-
-export { getLocalStorage as g, setLocalStorage as s };