@gateweb/react-utils 1.13.0 → 1.14.0

package/README.md

@@ -1,74 +1,162 @@
-# react-utils
+# @gateweb/react-utils
 
-**_react-utils_** is a collection of utility functions for GateWeb's React projects.
+**`@gateweb/react-utils`** is a comprehensive, TypeScript-first utility library designed to streamline development in React projects at GateWeb. It provides a collection of robust, well-tested, and reusable functions and hooks, covering everything from date manipulation and type conversion to custom hooks and web APIs.
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/@gateweb/react-utils.svg)](https://www.npmjs.com/package/@gateweb/react-utils)
+
+## ✨ Features
+
+- **React Hooks**: A collection of useful hooks like `useCountdown` and `useValue`.
+- **Date Utilities**: Powerful and flexible functions for handling dates and time periods, built on top of `dayjs`.
+- **Core Helpers**: A wide range of utilities for type conversion (`bytes`, `searchParams`), case style formatting, object manipulation, and more.
+- **Web APIs**: Simplified functions for common web tasks like file downloads (`download`) and managing browser storage (`webStorage`).
+- **Validation**: A set of predefined regex patterns and validation functions for common data types.
+- **TypeScript First**: Fully written in TypeScript, providing excellent type safety and autocompletion out of the box.
+- **Lightweight & Tree-Shakable**: Built with `bunchee` to ensure minimal bundle size.
+
+## 📦 Installation
 
 ```bash
+# With pnpm (recommended)
+pnpm add @gateweb/react-utils
+
+# With npm
 npm install @gateweb/react-utils
-# or
+
+# With yarn
 yarn add @gateweb/react-utils
-# or
-pnpm add @gateweb/react-utils
 ```
 
-## Usage
+## 🚀 Usage
+
+Here are some examples of the most common utilities.
+
+### React Hooks
+
+#### `useCountdown`
+
+A hook to manage a countdown timer.
 
 ```tsx
-import { formatAmount } from '@gateweb/react-utils';
+import { useCountdown } from '@gateweb/react-utils';
+
+function MyComponent() {
+  const { count, start, stop, reset } = useCountdown({ initialValue: 60 });
+
+  return (
+    <div>
+      <p>Countdown: {count}</p>
+      <button onClick={start}>Start</button>
+      <button onClick={stop}>Stop</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
+}
 ```
 
-## How to Release a New Version
+### Date Utilities
+
+#### `formatDate`
+
+Format a date object or string into a custom format.
 
-### Manually Bump the Version
+```ts
+import { formatDate } from '@gateweb/react-utils';
 
-1. Update the version in `package.json`
+const formattedDate = formatDate(new Date(), 'YYYY-MM-DD');
+console.log(formattedDate); // e.g., "2023-10-27"
+```
+
+#### `getPeriod`
 
-   ```diff
-   # e.g. bump the version from 0.1.0 to 0.1.1
-   {
-       "name": "@gateweb/react-utils",
-   -   "version": "0.1.0"
-   +   "version": "0.1.1"
-   }
-   ```
+Get a predefined date period, like "last 7 days".
 
-2. Install the dependencies and build the package
+```ts
+import { getPeriod } from '@gateweb/react-utils';
+
+const last7Days = getPeriod('last_7_days');
+console.log(last7Days); // { startDate: Dayjs, endDate: Dayjs }
+```
 
-   ```sh
-   pnpm install
-   pnpm build
-   ```
+### Core Utilities
+
+#### `toCamelCase`
+
+Convert a string from snake_case or kebab-case to camelCase.
+
+```ts
+import { toCamelCase } from '@gateweb/react-utils';
+
+const camel = toCamelCase('hello_world-example');
+console.log(camel); // "helloWorldExample"
+```
+
+#### `bytesToSize`
+
+Convert bytes to a human-readable format (KB, MB, GB).
+
+```ts
+import { bytesToSize } from '@gateweb/react-utils';
+
+const size = bytesToSize(1024 * 1024 * 5); // 5MB
+console.log(size); // "5 MB"
+```
+
+### Web APIs
+
+#### `download`
+
+A simple utility to trigger a file download in the browser.
+
+```ts
+import { download } from '@gateweb/react-utils';
+
+function handleDownload() {
+  const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
+  download(blob, 'hello.txt');
+}
+```
 
-3. login to npm
+## 🤝 Contributing
 
-   ```sh
-   # make sure you have an npm account
-   pnpm login
-   # npm notice Log in on https://registry.npmjs.org/
-   # Login at:
-   # https://www.npmjs.com/login?next=/login/cli/390e514d-7aa5-4ee7-a13a-b17e6dd64518
-   # Press ENTER to open in the browser...
-   ```
+Contributions are welcome! To ensure a smooth development process, please follow these steps:
 
-4. Publish the package
+1.  **Fork & Clone**: Fork the repository and clone it to your local machine.
+2.  **Set Up**: This project uses `pnpm` as the package manager. Install dependencies with:
+    ```bash
+    pnpm install
+    ```
+3.  **Develop**: Create a new branch for your feature or bug fix.
+4.  **Test**: Write tests for your changes and ensure all existing tests pass.
 
-   ```sh
-   pnpm publish --access public --no-git-checks
-   ```
+    ```bash
+    # Run all tests
+    pnpm test
 
-5. Check the published package on npmjs.com
+    # Run tests in watch mode
+    pnpm test:watch
+    ```
 
-   [@gateweb/react-utils](https://www.npmjs.com/package/@gateweb/react-utils)
+5.  **Submit a Pull Request**: Push your changes to your fork and open a pull request to the `main` branch. Your code will be automatically linted and formatted upon commit.
 
-### Automatically Bump the Version
+## Publishing (For Maintainers)
 
-- When you merge a pull request to the `main` branch, the GitHub Action will automatically bump the version and publish the package to npm.
+### Manual Release
 
-- The version will follow the [Semantic Versioning](https://semver.org/) rules.
+1.  Update the version in `package.json`.
+2.  Install dependencies and build the package:
+    ```sh
+    pnpm install && pnpm build
+    ```
+3.  Log in to npm:
+    ```sh
+    pnpm login
+    ```
+4.  Publish the package:
+    ```sh
+    pnpm publish --access public --no-git-checks
+    ```
 
-## Notes
+### Automatic Release
 
-- You should use `pnpm` to develop this package.
-- This package is written in TypeScript and supports TypeScript out of the box.
-- This package is built with [bunchee](https://github.com/huozhi/bunchee) which is a zero-config build tool for TypeScript packages based on Rollup.
+When a pull request is merged into the `main` branch, the `release` GitHub Action will automatically bump the version, create a changelog, and publish the new version to npm. The version bump follows [Semantic Versioning](https.semver.org/) based on the commit messages (e.g., `feat:` for minor, `fix:` for patch).

package/dist/cjs/index.d.ts

@@ -404,7 +404,9 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * @param obj 要處理的物件
  * @param name 生成的 enum 名稱
- * @param scene 要使用的條件 (參考 example)
+ *
+ * @remarks
+ * 若需多場景 label，請傳入第三參數 scene，詳細用法請見範例。
  *
  * @example
  *
@@ -419,7 +421,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * // scenes 版本
  *
- * Status = { Enabled: { value: 'enabled', scenes: { webA: { label: '啟用' }, webB: { label: '激活' } } }, Disabled: { value: 'disabled', scenes: { webA: { label: '停用' }, webB: { label: '停止' }}}}
+ * const Status = { Enabled: { value: 'enabled', scenes: { webA: { label: '啟用' }, webB: { label: '激活' } } }, Disabled: { value: 'disabled', scenes: { webA: { label: '停用' }, webB: { label: '停止' }}}}
  * const { EnumStatusA, StatusAList, getStatusALabel } = createEnumLikeObject(Status, 'StatusA', 'webA');
  * console.log(EnumStatusA); // { Enabled: 'enabled', Disabled: 'disabled' }
  * console.log(StatusAList); // [ { key: 'Enabled', value: 'enabled', label: '啟用' }, { key: 'Disabled', value: 'disabled', label: '停用' }]
@@ -431,6 +433,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  * console.log(getStatusBLabel('enabled')); // '激活'
  *
  * ```
+ *
  */
 declare function createEnumLikeObject<T extends Record<string, {
     value: any;
@@ -576,6 +579,23 @@ declare function invariant(condition: any, message?: string | (() => string)): a
  */
 declare const isServer: () => boolean;
 
+type DeepPartialWithBooleanOverride<T> = {
+    [K in keyof T]?: T[K] extends object ? T[K] extends boolean ? T[K] : DeepPartialWithBooleanOverride<T[K]> | boolean : T[K];
+};
+/**
+ * 深度合併配置物件的通用工具
+ *
+ * @param defaultConfig - 預設配置
+ * @param customConfig - 自訂配置
+ *
+ * @example
+ * const defaultConfig = { a: true, b: { b1: true, b2: true, b3: false }, c: true, d: false };
+ * mergeConfig(defaultConfig, { b: { b1: false }, d: true }); // { a: true, b: { b1: false, b2: true, b3: false }, c: true, d: true }
+ * mergeConfig(defaultConfig, { b: false }); // { a: true, b: { b1: false, b2: false, b3: false }, c: true, d: false }
+ * mergeConfig(defaultConfig, { b: true }); // { a: true, b: { b1: true, b2: true, b3: true }, c: true, d: false }
+ */
+declare const mergeConfig: <T extends Record<string, any>>(defaultConfig: T, customConfig?: DeepPartialWithBooleanOverride<T>) => T;
+
 /**
  * 將物件中的某些 key 排除
  *
@@ -671,6 +691,18 @@ type RequiredBy<T, K extends keyof T, RemoveUndefined extends boolean = false> =
 type PartialBy<T, K extends keyof T, RemoveUndefined extends boolean = false> = Omit<T, K> & {
     [P in K]?: RemoveUndefined extends true ? Exclude<T[P], undefined> : T[P];
 };
+/**
+ * A utility function to deeply clone an object.
+ * @param obj - The object to clone.
+ *
+ * @example
+ *
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = deepClone(original);
+ * console.log(cloned); // { a: 1, b: { c: 2 } }
+ *
+ */
+declare const deepClone: <T>(obj: T) => T;
 
 /**
  * debounce function
@@ -983,6 +1015,30 @@ declare const validTaxId: (taxId: string) => boolean;
  * validateDateString('20210201', 'YYYYMM') // false
  */
 declare const validateDateString: (dateString: string, format: string) => boolean;
+/**
+ * 判斷 `value` 是否為 `null` 或 `undefined`
+ *
+ * @param value 值
+ *
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ * isNil(false); // false
+ * isNil({}); // false
+ *
+ * // TypeScript 型別縮窄應用
+ * function example(input?: string | null) {
+ *   if (isNil(input)) {
+ *     // input 型別會自動縮窄成 null | undefined
+ *     return 'No value';
+ *   }
+ *   // input 型別自動為 string
+ *   return input.toUpperCase();
+ * }
+ */
+declare const isNil: (value: unknown) => value is null | undefined;
 
 type TQueryProps<Q> = {
     /**
@@ -1042,7 +1098,7 @@ declare const useQueryContext: <Q>() => <T>(selector: (state: TQueryState<Q>) =>
  * and a Provider component for supplying context values.
  *
  * @template T - The value type for the context.
- * @returns {Object} An object containing:
+ * @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.
  *
@@ -1204,4 +1260,5 @@ declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefin
  */
 declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
 
-export { ByteSize, type MimeTypeExtension, MimeTypeMap, type MimeTypeValue, OtherMimeType, type PartialBy, QueryProvider, type RequiredBy, type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeRefs, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { ByteSize, MimeTypeMap, OtherMimeType, QueryProvider, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepClone, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, 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, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy, TCountdownActions };

package/dist/cjs/index.js

@@ -5,7 +5,7 @@ var queryStoreClient = require('./queryStore-client-q_SLGgYH.js');
 var React = require('react');
 var useCountdownClient = require('./useCountdown-client-uiqhgllY.js');
 var downloadClient = require('./download-client-DKxkL92w.js');
-var webStorageClient = require('./webStorage-client-BGQKUfrO.js');
+var webStorageClient = require('./webStorage-client-DHr9PcPl.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -507,6 +507,85 @@ const isObject = (value)=>value !== null && typeof value === 'object';
     }, {
         ...target
     });
+/**
+ * A utility function to deeply clone an object.
+ * @param obj - The object to clone.
+ *
+ * @example
+ *
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = deepClone(original);
+ * console.log(cloned); // { a: 1, b: { c: 2 } }
+ *
+ */ const deepClone = (obj)=>{
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item)=>deepClone(item));
+    }
+    const cloned = Object.keys(obj).reduce((acc, key)=>{
+        acc[key] = deepClone(obj[key]);
+        return acc;
+    }, {});
+    return cloned;
+};
+
+/**
+ * 將嵌套物件的所有屬性設為指定的布林值
+ * @param obj - 目標物件
+ * @param boolValue - 布林值
+ *
+ * @example
+ * const obj = { a: { b: 1, c: 2 }, d: 3 };
+ * const result = setBooleanToNestedObject(obj, true);
+ * console.log(result); // { a: { b: true, c: true }, d: true }
+ */ const setBooleanToNestedObject = (obj, boolValue)=>Object.entries(obj).reduce((acc, [key, value])=>{
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // 如果是嵌套物件，遞歸處理
+            acc[key] = setBooleanToNestedObject(value, boolValue);
+        } else {
+            // 如果是基本類型，設為布林值
+            acc[key] = boolValue;
+        }
+        return acc;
+    }, {});
+/**
+ * 深度合併配置物件的通用工具
+ *
+ * @param defaultConfig - 預設配置
+ * @param customConfig - 自訂配置
+ *
+ * @example
+ * const defaultConfig = { a: true, b: { b1: true, b2: true, b3: false }, c: true, d: false };
+ * mergeConfig(defaultConfig, { b: { b1: false }, d: true }); // { a: true, b: { b1: false, b2: true, b3: false }, c: true, d: true }
+ * mergeConfig(defaultConfig, { b: false }); // { a: true, b: { b1: false, b2: false, b3: false }, c: true, d: false }
+ * mergeConfig(defaultConfig, { b: true }); // { a: true, b: { b1: true, b2: true, b3: true }, c: true, d: false }
+ */ const mergeConfig = (defaultConfig, customConfig = {})=>{
+    // 深拷貝預設配置以避免修改原始物件
+    const result = deepClone(defaultConfig);
+    return Object.entries(customConfig).reduce((acc, [key, sourceValue])=>{
+        const targetValue = acc[key];
+        // 如果來源值為 null 或 undefined，跳過
+        if (sourceValue === null || sourceValue === undefined) {
+            return acc;
+        }
+        // 如果目標物件中對應的值是物件，且來源值是布林值
+        // 這是特殊情況：用布林值覆蓋整個嵌套物件
+        if (typeof targetValue === 'object' && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === 'boolean') {
+            // 將嵌套物件的所有屬性設為該布林值
+            acc[key] = setBooleanToNestedObject(targetValue, sourceValue);
+        } else if (typeof targetValue === 'object' && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === 'object' && sourceValue !== null && !Array.isArray(sourceValue)) {
+            acc[key] = mergeConfig(targetValue, sourceValue);
+        } else {
+            acc[key] = sourceValue;
+        }
+        return acc;
+    }, result);
+};
 
 /**
  * debounce function
@@ -916,8 +995,7 @@ const FILE_SIZE_UNITS = [
  *
  * isEmail().test('123') // false
  * isEmail().test('123@gmail.com') // true
- */ const isEmail = ()=>// eslint-disable-next-line
-    /^(?!\.)(?!.*\.\.)([A-Z0-9_+-\.]*)[A-Z0-9_+-]@([A-Z0-9][A-Z0-9\-]*\.)+[A-Z]{2,}$/i;
+ */ const isEmail = ()=>/^(?!\.)(?!.*\.\.)([A-Z0-9_+-\\.]*)[A-Z0-9_+-]@([A-Z0-9][A-Z0-9\\-]*\.)+[A-Z]{2,}$/i;
 /**
  * 日期字串
  *
@@ -1116,6 +1194,29 @@ const FILE_SIZE_UNITS = [
     // 再用 dayjs 驗證是否為有效日期
     return dayjs__default.default(dateString, format, true).isValid();
 };
+/**
+ * 判斷 `value` 是否為 `null` 或 `undefined`
+ *
+ * @param value 值
+ *
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ * isNil(false); // false
+ * isNil({}); // false
+ *
+ * // TypeScript 型別縮窄應用
+ * function example(input?: string | null) {
+ *   if (isNil(input)) {
+ *     // input 型別會自動縮窄成 null | undefined
+ *     return 'No value';
+ *   }
+ *   // input 型別自動為 string
+ *   return input.toUpperCase();
+ * }
+ */ const isNil = (value)=>value === null || value === undefined;
 
 /**
  * Creates a strongly-typed React Context and Provider pair for data sharing.
@@ -1125,7 +1226,7 @@ const FILE_SIZE_UNITS = [
  * and a Provider component for supplying context values.
  *
  * @template T - The value type for the context.
- * @returns {Object} An object containing:
+ * @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.
  *
@@ -1310,6 +1411,7 @@ exports.convertBytes = convertBytes;
 exports.createDataContext = createDataContext;
 exports.createEnumLikeObject = createEnumLikeObject;
 exports.debounce = debounce;
+exports.deepClone = deepClone;
 exports.deepMerge = deepMerge;
 exports.extractEnumLikeObject = extractEnumLikeObject;
 exports.fakeApi = fakeApi;
@@ -1326,6 +1428,7 @@ exports.isDateTimeString = isDateTimeString;
 exports.isEmail = isEmail;
 exports.isEnglish = isEnglish;
 exports.isEqual = isEqual;
+exports.isNil = isNil;
 exports.isNonZeroStart = isNonZeroStart;
 exports.isNumber = isNumber;
 exports.isNumberAtLeastN = isNumberAtLeastN;
@@ -1337,6 +1440,7 @@ exports.isTWPhone = isTWPhone;
 exports.isTimeString = isTimeString;
 exports.isValidPassword = isValidPassword;
 exports.maskString = maskString;
+exports.mergeConfig = mergeConfig;
 exports.mergeRefs = mergeRefs;
 exports.objectToSearchParams = objectToSearchParams;
 exports.omit = omit;

package/dist/cjs/types.d.ts

@@ -187,5 +187,18 @@ type TChangeKeyType<T, K extends keyof T, V> = Omit<T, K> & {
 type MapToType<T extends Record<any, any>, A = any> = {
     [K in keyof T]: A;
 };
+/**
+ * 覆寫 T 指定屬性的型別，保留其他屬性。
+ *
+ * @template T 原始型別
+ * @template R 欲覆寫的 key-value 結構
+ *
+ * @example
+ * type User = { id: number; name: string }
+ * type FormUser = OverrideProps<User, { id: string }> // { id: string; name: string }
+ */
+type OverrideProps<T, R extends {
+    [K in keyof R]: any;
+}> = Omit<T, keyof R> & R;
 
-export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };
+export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, OverrideProps, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };

package/dist/cjs/{webStorage-client-BGQKUfrO.js → webStorage-client-DHr9PcPl.js}

@@ -20,7 +20,7 @@
         } else {
             currentObject = JSON.parse(storage);
         }
-    } catch (error) {
+    } catch (_error) {
         return undefined;
     }
     // let currentObject = JSON.parse(storage);

package/dist/es/index.d.mts

@@ -404,7 +404,9 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * @param obj 要處理的物件
  * @param name 生成的 enum 名稱
- * @param scene 要使用的條件 (參考 example)
+ *
+ * @remarks
+ * 若需多場景 label，請傳入第三參數 scene，詳細用法請見範例。
  *
  * @example
  *
@@ -419,7 +421,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * // scenes 版本
  *
- * Status = { Enabled: { value: 'enabled', scenes: { webA: { label: '啟用' }, webB: { label: '激活' } } }, Disabled: { value: 'disabled', scenes: { webA: { label: '停用' }, webB: { label: '停止' }}}}
+ * const Status = { Enabled: { value: 'enabled', scenes: { webA: { label: '啟用' }, webB: { label: '激活' } } }, Disabled: { value: 'disabled', scenes: { webA: { label: '停用' }, webB: { label: '停止' }}}}
  * const { EnumStatusA, StatusAList, getStatusALabel } = createEnumLikeObject(Status, 'StatusA', 'webA');
  * console.log(EnumStatusA); // { Enabled: 'enabled', Disabled: 'disabled' }
  * console.log(StatusAList); // [ { key: 'Enabled', value: 'enabled', label: '啟用' }, { key: 'Disabled', value: 'disabled', label: '停用' }]
@@ -431,6 +433,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  * console.log(getStatusBLabel('enabled')); // '激活'
  *
  * ```
+ *
  */
 declare function createEnumLikeObject<T extends Record<string, {
     value: any;
@@ -576,6 +579,23 @@ declare function invariant(condition: any, message?: string | (() => string)): a
  */
 declare const isServer: () => boolean;
 
+type DeepPartialWithBooleanOverride<T> = {
+    [K in keyof T]?: T[K] extends object ? T[K] extends boolean ? T[K] : DeepPartialWithBooleanOverride<T[K]> | boolean : T[K];
+};
+/**
+ * 深度合併配置物件的通用工具
+ *
+ * @param defaultConfig - 預設配置
+ * @param customConfig - 自訂配置
+ *
+ * @example
+ * const defaultConfig = { a: true, b: { b1: true, b2: true, b3: false }, c: true, d: false };
+ * mergeConfig(defaultConfig, { b: { b1: false }, d: true }); // { a: true, b: { b1: false, b2: true, b3: false }, c: true, d: true }
+ * mergeConfig(defaultConfig, { b: false }); // { a: true, b: { b1: false, b2: false, b3: false }, c: true, d: false }
+ * mergeConfig(defaultConfig, { b: true }); // { a: true, b: { b1: true, b2: true, b3: true }, c: true, d: false }
+ */
+declare const mergeConfig: <T extends Record<string, any>>(defaultConfig: T, customConfig?: DeepPartialWithBooleanOverride<T>) => T;
+
 /**
  * 將物件中的某些 key 排除
  *
@@ -671,6 +691,18 @@ type RequiredBy<T, K extends keyof T, RemoveUndefined extends boolean = false> =
 type PartialBy<T, K extends keyof T, RemoveUndefined extends boolean = false> = Omit<T, K> & {
     [P in K]?: RemoveUndefined extends true ? Exclude<T[P], undefined> : T[P];
 };
+/**
+ * A utility function to deeply clone an object.
+ * @param obj - The object to clone.
+ *
+ * @example
+ *
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = deepClone(original);
+ * console.log(cloned); // { a: 1, b: { c: 2 } }
+ *
+ */
+declare const deepClone: <T>(obj: T) => T;
 
 /**
  * debounce function
@@ -983,6 +1015,30 @@ declare const validTaxId: (taxId: string) => boolean;
  * validateDateString('20210201', 'YYYYMM') // false
  */
 declare const validateDateString: (dateString: string, format: string) => boolean;
+/**
+ * 判斷 `value` 是否為 `null` 或 `undefined`
+ *
+ * @param value 值
+ *
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ * isNil(false); // false
+ * isNil({}); // false
+ *
+ * // TypeScript 型別縮窄應用
+ * function example(input?: string | null) {
+ *   if (isNil(input)) {
+ *     // input 型別會自動縮窄成 null | undefined
+ *     return 'No value';
+ *   }
+ *   // input 型別自動為 string
+ *   return input.toUpperCase();
+ * }
+ */
+declare const isNil: (value: unknown) => value is null | undefined;
 
 type TQueryProps<Q> = {
     /**
@@ -1042,7 +1098,7 @@ declare const useQueryContext: <Q>() => <T>(selector: (state: TQueryState<Q>) =>
  * and a Provider component for supplying context values.
  *
  * @template T - The value type for the context.
- * @returns {Object} An object containing:
+ * @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.
  *
@@ -1204,4 +1260,5 @@ declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefin
  */
 declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
 
-export { ByteSize, type MimeTypeExtension, MimeTypeMap, type MimeTypeValue, OtherMimeType, type PartialBy, QueryProvider, type RequiredBy, type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeRefs, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { ByteSize, MimeTypeMap, OtherMimeType, QueryProvider, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepClone, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, 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, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy, TCountdownActions };

package/dist/es/index.mjs

@@ -1,9 +1,9 @@
 import dayjs from 'dayjs';
-export { Q as QueryProvider, u as useQueryContext } from './queryStore-client-vG-bXFYm.mjs';
-import React, { useContext, useMemo, createContext, useState, useCallback } from 'react';
+export { Q as QueryProvider, u as useQueryContext } from './queryStore-client-CFQTVwrg.mjs';
+import React, { useMemo, createContext, useContext, useState, useCallback } from 'react';
 export { u as useCountdown } from './useCountdown-client-t52WIHfq.mjs';
 export { d as downloadFile } from './download-client-CnaJ0p_f.mjs';
-export { g as getLocalStorage, s as setLocalStorage } from './webStorage-client-Pd-loNCg.mjs';
+export { g as getLocalStorage, s as setLocalStorage } from './webStorage-client-W1DItzhS.mjs';
 
 const FILE_SIZE_UNITS$1 = [
     'Bytes',
@@ -500,6 +500,85 @@ const isObject = (value)=>value !== null && typeof value === 'object';
     }, {
         ...target
     });
+/**
+ * A utility function to deeply clone an object.
+ * @param obj - The object to clone.
+ *
+ * @example
+ *
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = deepClone(original);
+ * console.log(cloned); // { a: 1, b: { c: 2 } }
+ *
+ */ const deepClone = (obj)=>{
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item)=>deepClone(item));
+    }
+    const cloned = Object.keys(obj).reduce((acc, key)=>{
+        acc[key] = deepClone(obj[key]);
+        return acc;
+    }, {});
+    return cloned;
+};
+
+/**
+ * 將嵌套物件的所有屬性設為指定的布林值
+ * @param obj - 目標物件
+ * @param boolValue - 布林值
+ *
+ * @example
+ * const obj = { a: { b: 1, c: 2 }, d: 3 };
+ * const result = setBooleanToNestedObject(obj, true);
+ * console.log(result); // { a: { b: true, c: true }, d: true }
+ */ const setBooleanToNestedObject = (obj, boolValue)=>Object.entries(obj).reduce((acc, [key, value])=>{
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // 如果是嵌套物件，遞歸處理
+            acc[key] = setBooleanToNestedObject(value, boolValue);
+        } else {
+            // 如果是基本類型，設為布林值
+            acc[key] = boolValue;
+        }
+        return acc;
+    }, {});
+/**
+ * 深度合併配置物件的通用工具
+ *
+ * @param defaultConfig - 預設配置
+ * @param customConfig - 自訂配置
+ *
+ * @example
+ * const defaultConfig = { a: true, b: { b1: true, b2: true, b3: false }, c: true, d: false };
+ * mergeConfig(defaultConfig, { b: { b1: false }, d: true }); // { a: true, b: { b1: false, b2: true, b3: false }, c: true, d: true }
+ * mergeConfig(defaultConfig, { b: false }); // { a: true, b: { b1: false, b2: false, b3: false }, c: true, d: false }
+ * mergeConfig(defaultConfig, { b: true }); // { a: true, b: { b1: true, b2: true, b3: true }, c: true, d: false }
+ */ const mergeConfig = (defaultConfig, customConfig = {})=>{
+    // 深拷貝預設配置以避免修改原始物件
+    const result = deepClone(defaultConfig);
+    return Object.entries(customConfig).reduce((acc, [key, sourceValue])=>{
+        const targetValue = acc[key];
+        // 如果來源值為 null 或 undefined，跳過
+        if (sourceValue === null || sourceValue === undefined) {
+            return acc;
+        }
+        // 如果目標物件中對應的值是物件，且來源值是布林值
+        // 這是特殊情況：用布林值覆蓋整個嵌套物件
+        if (typeof targetValue === 'object' && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === 'boolean') {
+            // 將嵌套物件的所有屬性設為該布林值
+            acc[key] = setBooleanToNestedObject(targetValue, sourceValue);
+        } else if (typeof targetValue === 'object' && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === 'object' && sourceValue !== null && !Array.isArray(sourceValue)) {
+            acc[key] = mergeConfig(targetValue, sourceValue);
+        } else {
+            acc[key] = sourceValue;
+        }
+        return acc;
+    }, result);
+};
 
 /**
  * debounce function
@@ -909,8 +988,7 @@ const FILE_SIZE_UNITS = [
  *
  * isEmail().test('123') // false
  * isEmail().test('123@gmail.com') // true
- */ const isEmail = ()=>// eslint-disable-next-line
-    /^(?!\.)(?!.*\.\.)([A-Z0-9_+-\.]*)[A-Z0-9_+-]@([A-Z0-9][A-Z0-9\-]*\.)+[A-Z]{2,}$/i;
+ */ const isEmail = ()=>/^(?!\.)(?!.*\.\.)([A-Z0-9_+-\\.]*)[A-Z0-9_+-]@([A-Z0-9][A-Z0-9\\-]*\.)+[A-Z]{2,}$/i;
 /**
  * 日期字串
  *
@@ -1109,6 +1187,29 @@ const FILE_SIZE_UNITS = [
     // 再用 dayjs 驗證是否為有效日期
     return dayjs(dateString, format, true).isValid();
 };
+/**
+ * 判斷 `value` 是否為 `null` 或 `undefined`
+ *
+ * @param value 值
+ *
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ * isNil(false); // false
+ * isNil({}); // false
+ *
+ * // TypeScript 型別縮窄應用
+ * function example(input?: string | null) {
+ *   if (isNil(input)) {
+ *     // input 型別會自動縮窄成 null | undefined
+ *     return 'No value';
+ *   }
+ *   // input 型別自動為 string
+ *   return input.toUpperCase();
+ * }
+ */ const isNil = (value)=>value === null || value === undefined;
 
 /**
  * Creates a strongly-typed React Context and Provider pair for data sharing.
@@ -1118,7 +1219,7 @@ const FILE_SIZE_UNITS = [
  * and a Provider component for supplying context values.
  *
  * @template T - The value type for the context.
- * @returns {Object} An object containing:
+ * @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.
  *
@@ -1285,4 +1386,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, deepMerge, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeRefs, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useValue, validTaxId, validateDateString, validateFileType, wait };
+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, rocEraToAd, searchParamsToObject, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useValue, validTaxId, validateDateString, validateFileType, wait };

package/dist/es/{queryStore-client-vG-bXFYm.mjs → queryStore-client-CFQTVwrg.mjs}

@@ -1,5 +1,5 @@
 'use client';
-import React, { useRef, useContext, createContext } from 'react';
+import React, { useRef, createContext, useContext } from 'react';
 import { createStore } from 'zustand';
 import { useStoreWithEqualityFn } from 'zustand/traditional';
 

package/dist/es/types.d.mts

@@ -187,5 +187,18 @@ type TChangeKeyType<T, K extends keyof T, V> = Omit<T, K> & {
 type MapToType<T extends Record<any, any>, A = any> = {
     [K in keyof T]: A;
 };
+/**
+ * 覆寫 T 指定屬性的型別，保留其他屬性。
+ *
+ * @template T 原始型別
+ * @template R 欲覆寫的 key-value 結構
+ *
+ * @example
+ * type User = { id: number; name: string }
+ * type FormUser = OverrideProps<User, { id: string }> // { id: string; name: string }
+ */
+type OverrideProps<T, R extends {
+    [K in keyof R]: any;
+}> = Omit<T, keyof R> & R;
 
-export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };
+export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, OverrideProps, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };

package/dist/es/{webStorage-client-Pd-loNCg.mjs → webStorage-client-W1DItzhS.mjs}

@@ -20,7 +20,7 @@
         } else {
             currentObject = JSON.parse(storage);
         }
-    } catch (error) {
+    } catch (_error) {
         return undefined;
     }
     // let currentObject = JSON.parse(storage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [
@@ -36,33 +36,38 @@
   },
   "dependencies": {
     "dayjs": "^1.11.13",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "use-sync-external-store": "^1.5.0",
-    "zustand": "^5.0.3"
+    "zustand": "^5.0.6"
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.5.0",
-    "@commitlint/config-conventional": "^19.5.0",
-    "@gateweb/eslint-config-gateweb": "^1.0.6",
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@gateweb/eslint-config-gateweb": "^2.1.1",
     "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/react": "^16.2.0",
-    "@types/jest": "^29.5.13",
-    "@types/node": "^22.7.7",
-    "@types/react": "^19.0.8",
-    "@vitest/coverage-v8": "^2.1.4",
-    "@vitest/ui": "2.1.4",
+    "@testing-library/react": "^16.3.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.1.0",
+    "@types/react": "^19.1.8",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "3.2.4",
     "bunchee": "^5.6.1",
-    "eslint": "^8",
-    "husky": "^9.1.6",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "lint-staged": "^15.2.10",
-    "prettier": "^3.3.3",
-    "ts-jest": "^29.2.5",
+    "eslint": "^9.31.0",
+    "husky": "^9.1.7",
+    "jest": "^30.0.5",
+    "jest-environment-jsdom": "^30.0.5",
+    "lint-staged": "^16.1.2",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.4"
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
   },
   "scripts": {
     "run-code": "ts-node src/period.ts",