@gateweb/react-utils 1.12.2 → 1.14.0

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',
@@ -231,11 +231,31 @@ function createEnumLikeObject(obj, name, scene) {
         }, time);
     });
 
+const MimeTypeMap = {
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    gif: 'image/gif',
+    png: 'image/png',
+    pdf: 'application/pdf',
+    zip: 'application/zip',
+    csv: 'text/csv',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    txt: 'text/plain'
+};
+const OtherMimeType = 'application/octet-stream';
+
 /**
- * 檢查檔案是否為合法的 MIME 類型
+ * 檢查檔案是否為合法的檔案類型
+ *
+ * `accepts` 可同時接受副檔名以及 MIME 類型
  *
  * @param file 檔案
- * @param accepts 允許的 MIME 類型
+ * @param accepts 允許的類型
  *
  * @example
  *
@@ -243,21 +263,24 @@ function createEnumLikeObject(obj, name, scene) {
  * validateFileType({ type: 'image/png' }, ['image/png', 'image/jpeg']) // true
  * validateFileType({ type: 'image/png' }, ['image/jpeg']) // false
  * validateFileType({ type: 'image/png' }, ['image/*']) // true
+ * validateFileType({ name: '圖片.png', type: 'image/png' }, ['.png']) // true
  * ```
  */ const validateFileType = (file, accepts)=>{
     if (accepts.length === 0) return true;
     // 獲取文件的MIME類型
     const fileMimeType = file.type;
+    // 提取副檔名（含 .，且轉小寫）
+    const fileExt = file.name.includes('.') ? `.${file.name.split('.').pop().toLowerCase()}` : '';
     return accepts.some((accept)=>{
+        if (accept.startsWith('.')) {
+            // 以副檔名檢查，忽略大小寫
+            return fileExt === accept.toLowerCase();
+        }
         if (accept === fileMimeType) {
             return true;
         }
         if (accept.endsWith('/*')) {
-            const acceptedCategory = accept.split('/')[0];
-            const fileCategory = fileMimeType.split('/')[0];
-            if (acceptedCategory === fileCategory) {
-                return true;
-            }
+            return accept.split('/')[0] === fileMimeType.split('/')[0];
         }
         return false;
     });
@@ -284,32 +307,70 @@ function createEnumLikeObject(obj, name, scene) {
  * getMimeType('xlsx') // 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  * getMimeType('doc') // 'application/msword'
  * getMimeType('docx') // 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+ *
+ * @deprecated use `parseFileInfoFromFilename` instead
  */ const getMimeType = (fileName)=>{
-    switch((fileName.split('.').pop() || '').toLocaleLowerCase()){
-        case 'jpeg':
-        case 'jpg':
-            return 'image/jpeg';
-        case 'png':
-            return 'image/png';
-        case 'pdf':
-            return 'application/pdf';
-        case 'zip':
-            return 'application/zip';
-        case 'csv':
-            return 'text/csv';
-        case 'xls':
-            return 'application/vnd.ms-excel';
-        case 'xlsx':
-            return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
-        case 'doc':
-            return 'application/msword';
-        case 'docx':
-            return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
-        case 'txt':
-            return 'text/plain';
-        default:
-            return 'application/octet-stream';
+    const ext = (fileName.split('.').pop() || '').toLowerCase();
+    return MimeTypeMap[ext] ?? OtherMimeType;
+};
+/**
+ * 用來解析後端在 response header content-disposition 的內容
+ *
+ * 一般來說格式會有以下兩種
+ *
+ * - Content-Disposition: attachment; filename="file name.jpg"
+ * - Content-Disposition: attachment; filename*=UTF-8''file%20name2.jpg
+ *
+ * 如果格式正確就會取得檔案名稱(包含副檔名)，優先取 filename* 內的內容
+ *
+ * @param disposition Content-Disposition
+ *
+ * @example
+ *
+ * parseFilenameFromDisposition('attachment; filename="file name1.jpg') // file name.jpg
+ * parseFilenameFromDisposition('attachment; filename*=UTF-8''file%20name2.jpg') // file name2.jpg
+ * parseFilenameFromDisposition('attachment; filename="file name.jpg; filename*=UTF-8''file%20name2.jpg') // file name2.jpg
+ */ const parseFilenameFromDisposition = (disposition)=>{
+    // 1. 先找 filename*
+    const filenameStarMatch = disposition.match(/filename\*\s*=\s*(?:UTF-8'')?([^;]+)/i);
+    if (filenameStarMatch && filenameStarMatch[1]) {
+        // 依 RFC 5987 格式（UTF-8''URL-ENCODED），要先 decode
+        try {
+            return decodeURIComponent(filenameStarMatch[1].replace(/(^['"]|['"]$)/g, ''));
+        } catch  {
+            // fallback，如果 decode 失敗，直接傳回原值
+            return filenameStarMatch[1];
+        }
     }
+    // 2. 沒有 filename*，再找 filename
+    const filenameMatch = disposition.match(/filename\s*=\s*("?)([^";]+)\1/i);
+    if (filenameMatch && filenameMatch[2]) {
+        return filenameMatch[2];
+    }
+    // 3. 都沒有則 undefined
+    return undefined;
+};
+/**
+ * 解析 `filename` 回傳檔名、副檔名、MIME type
+ *
+ * @param filename 檔案名稱
+ *
+ * @example
+ *
+ * parseFileInfoFromFilename('image.jpg') // ['image', 'jpg', 'image/jpeg']
+ * parseFileInfoFromFilename('image') // ['image', '', 'application/octet-stream']
+ */ const parseFileInfoFromFilename = (filename)=>{
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1) return [
+        filename,
+        '',
+        OtherMimeType
+    ]; // 沒有副檔名
+    return [
+        filename.slice(0, lastDot),
+        filename.slice(lastDot + 1),
+        MimeTypeMap[filename.slice(lastDot + 1)] ?? OtherMimeType
+    ];
 };
 
 // const isProduction: boolean = process.env.NODE_ENV === 'production';
@@ -439,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
@@ -848,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;
 /**
  * 日期字串
  *
@@ -1048,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.
@@ -1057,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.
  *
@@ -1224,4 +1386,4 @@ function mergeRefs(refs) {
     return dayjs(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-export { ByteSize, 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, 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.12.2",
+  "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",