@gateweb/react-utils 2.0.0 → 2.2.0

package/dist/cjs/client.d.ts

@@ -1,4 +1,5 @@
-import React, { ReactNode } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
 import { AtLeastOne } from './types.js';
 
 type TStoreProps<S> = {
@@ -88,7 +89,7 @@ type TInitialProps$1<S> = TStoreProps<S> & {
  * ```
  */
 declare const createStoreContext: <S>() => {
-    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React.JSX.Element;
+    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React__default.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React__default.JSX.Element;
     useStore: <T>(selector: (state: TStoreState<S>) => T, equalityFn?: (left: T, right: T) => boolean) => T;
 };
 
@@ -121,7 +122,7 @@ type TInitialProps<Q> = Partial<TQueryProps<Q> & {
  *
  * @deprecated use `StoreProvider` from `core/store` instead
  */
-declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.PropsWithChildren<TInitialProps<Q>>) => React.JSX.Element;
+declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React__default.PropsWithChildren<TInitialProps<Q>>) => React__default.JSX.Element;
 /**
  * hook to get the store from the context
  *
@@ -180,7 +181,7 @@ declare const createDataContext: <T>() => {
     readonly DataProvider: ({ children, value }: {
         children: ReactNode;
         value: T;
-    }) => React.JSX.Element;
+    }) => React__default.JSX.Element;
 };
 
 type TCountdownActions = {
@@ -227,6 +228,27 @@ type UseDisclosureReturn = {
  */
 declare function useDisclosure(initialState?: boolean): UseDisclosureReturn;
 
+type Options = {
+    /** 滾輪轉成水平位移的倍率（觸控板通常較小，滑鼠滾輪較大） */
+    speed?: number;
+    /** 是否在按住 Shift 時改走瀏覽器原生（通常 Shift+滾輪就是橫向） */
+    respectShiftKey?: boolean;
+};
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */
+declare const useHorizontalWheel: <T extends HTMLElement>({ speed, respectShiftKey, }?: Options) => React.RefObject<T | null>;
+
 type TValueOptions<T> = AtLeastOne<{
     /**
      * The controlled value.
@@ -250,7 +272,7 @@ type TValueOptions<T> = AtLeastOne<{
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
-declare function mergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;
+declare function mergeRefs<T = any>(refs: Array<React__default.MutableRefObject<T> | React__default.LegacyRef<T> | undefined | null>): React__default.RefCallback<T>;
 
 /**
  * Downloads a file from a given source.
@@ -285,5 +307,5 @@ declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefin
  */
 declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
 
-export { QueryProvider, createDataContext, createStoreContext, downloadFile, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useQueryContext, useValue };
+export { QueryProvider, createDataContext, createStoreContext, downloadFile, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useHorizontalWheel, useQueryContext, useValue };
 export type { TCountdownActions, UseDisclosureReturn };

package/dist/cjs/client.js

@@ -5,6 +5,7 @@ var queryStore12s = require('./queryStore-12s-JzzXvjJC.js');
 var React = require('react');
 var useCountdown12s = require('./useCountdown-12s-uiqhgllY.js');
 var useDisclosure12s = require('./useDisclosure-12s-SZtbSE4A.js');
+var useHorizontalWheel12s = require('./useHorizontalWheel-12s-bwbWVJeM.js');
 var download12s = require('./download-12s-DKxkL92w.js');
 var webStorage12s = require('./webStorage-12s-0RtNO_uc.js');
 
@@ -111,6 +112,7 @@ exports.QueryProvider = queryStore12s.QueryProvider;
 exports.useQueryContext = queryStore12s.useQueryContext;
 exports.useCountdown = useCountdown12s.useCountdown;
 exports.useDisclosure = useDisclosure12s.useDisclosure;
+exports.useHorizontalWheel = useHorizontalWheel12s.useHorizontalWheel;
 exports.downloadFile = download12s.downloadFile;
 exports.getLocalStorage = webStorage12s.getLocalStorage;
 exports.setLocalStorage = webStorage12s.setLocalStorage;

package/dist/cjs/index.d.ts

@@ -706,6 +706,35 @@ declare function invariant(condition: any, message?: string | (() => string)): a
  */
 declare const isServer: () => boolean;
 
+type MaskKeySelector = string | ((key: string, value: unknown, path: Array<string | number>) => boolean);
+/**
+ * 深度走訪物件/陣列，將指定鍵名且值為字串的欄位遮罩為固定字串（預設 "******"）。
+ *
+ * - 預設僅遮罩鍵名等於 `password` 的欄位（區分大小寫）
+ * - 可傳入「字串鍵名」或「函式選擇器」來自訂要遮罩的欄位
+ * - 僅在值為字串時遮罩，其他型別維持原樣
+ * - 不變更輸入參考；回傳全新的資料結構
+ * - 函式選擇器會收到 `key`、`value` 與 `path`（到該鍵的路徑，陣列用索引）
+ * - 支援巢狀物件與陣列
+ *
+ * @param input - 來源資料
+ * @param mask - 遮罩字串，預設為 "******"
+ * @param selector - 欄位選擇器，字串或函式，預設 'password'
+ * @returns 回傳遮罩後的新資料
+ *
+ * @example
+ * const input = { password: 'secret', user: { password: 'abc' }, list: [{ password: 'x' }, { ok: 1 }] };
+ * const output = maskPasswords(input);
+ * // { password: '******', user: { password: '******' }, list: [{ password: '******' }, { ok: 1 }] }
+ *
+ * // 指定鍵名
+ * maskPasswords({ secret: 'xxx' }, '***', 'secret'); // { secret: '***' }
+ *
+ * // 使用函式選擇器（鍵名包含 'pass' 都遮）
+ * maskPasswords({ password: 'a', passcode: 'b' }, '***', (k) => k.includes('pass')); // { password: '***', passcode: '***' }
+ */
+declare const maskPasswords: <T>(input: T, mask?: string, selector?: MaskKeySelector) => T;
+
 type DeepPartialWithBooleanOverride<T> = {
     [K in keyof T]?: T[K] extends object ? T[K] extends boolean ? T[K] : DeepPartialWithBooleanOverride<T[K]> | boolean : T[K];
 };
@@ -1232,5 +1261,5 @@ declare const generatePeriodArray: () => string[];
  */
 declare const getCurrentPeriod: () => string;
 
-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 };
-export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };
+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, maskPasswords, 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 };
+export type { MaskKeySelector, MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };

package/dist/cjs/index.js

@@ -493,6 +493,74 @@ message) {
  * 判斷執行環境是否為 Server(node.js) 端
  */ const isServer = ()=>typeof window === 'undefined';
 
+/**
+ * 深度走訪物件/陣列，將指定鍵名且值為字串的欄位遮罩為固定字串（預設 "******"）。
+ *
+ * - 預設僅遮罩鍵名等於 `password` 的欄位（區分大小寫）
+ * - 可傳入「字串鍵名」或「函式選擇器」來自訂要遮罩的欄位
+ * - 僅在值為字串時遮罩，其他型別維持原樣
+ * - 不變更輸入參考；回傳全新的資料結構
+ * - 函式選擇器會收到 `key`、`value` 與 `path`（到該鍵的路徑，陣列用索引）
+ * - 支援巢狀物件與陣列
+ *
+ * @param input - 來源資料
+ * @param mask - 遮罩字串，預設為 "******"
+ * @param selector - 欄位選擇器，字串或函式，預設 'password'
+ * @returns 回傳遮罩後的新資料
+ *
+ * @example
+ * const input = { password: 'secret', user: { password: 'abc' }, list: [{ password: 'x' }, { ok: 1 }] };
+ * const output = maskPasswords(input);
+ * // { password: '******', user: { password: '******' }, list: [{ password: '******' }, { ok: 1 }] }
+ *
+ * // 指定鍵名
+ * maskPasswords({ secret: 'xxx' }, '***', 'secret'); // { secret: '***' }
+ *
+ * // 使用函式選擇器（鍵名包含 'pass' 都遮）
+ * maskPasswords({ password: 'a', passcode: 'b' }, '***', (k) => k.includes('pass')); // { password: '***', passcode: '***' }
+ */ const maskPasswords = (input, mask = '******', selector = 'password')=>{
+    const isObject = (val)=>val !== null && typeof val === 'object' && !Array.isArray(val) && !(val instanceof Date);
+    const shouldMask = (key, value, path)=>{
+        if (typeof selector === 'string') {
+            return key === selector && typeof value === 'string';
+        }
+        return selector(key, value, path) && typeof value === 'string';
+    };
+    const walk = (val, path)=>{
+        if (val === null || val === undefined) return val;
+        if (Array.isArray(val)) {
+            return val.map((item, idx)=>walk(item, [
+                    ...path,
+                    idx
+                ]));
+        }
+        if (val instanceof Date) {
+            return new Date(val.getTime());
+        }
+        if (isObject(val)) {
+            const result = Object.entries(val).reduce((acc, [key, v])=>{
+                const nextPath = [
+                    ...path,
+                    key
+                ];
+                if (shouldMask(key, v, nextPath)) {
+                    return {
+                        ...acc,
+                        [key]: mask
+                    };
+                }
+                return {
+                    ...acc,
+                    [key]: walk(v, nextPath)
+                };
+            }, {});
+            return result;
+        }
+        return val;
+    };
+    return walk(input, []);
+};
+
 /**
  * 將物件中的某些 key 排除
  *
@@ -1446,6 +1514,7 @@ exports.isTWMobile = isTWMobile;
 exports.isTWPhone = isTWPhone;
 exports.isTimeString = isTimeString;
 exports.isValidPassword = isValidPassword;
+exports.maskPasswords = maskPasswords;
 exports.maskString = maskString;
 exports.mergeConfig = mergeConfig;
 exports.objectToSearchParams = objectToSearchParams;

package/dist/cjs/types.d.ts

@@ -137,6 +137,8 @@ type OnlyOne<T> = {
         [P in Exclude<keyof T, K>]?: never;
     };
 }[keyof T];
+type Builtin = string | number | boolean | bigint | symbol | null | undefined;
+type NonRecursive = Builtin | Function | Date | RegExp | Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any> | Promise<any>;
 /**
  * A utility type that makes all properties in the generic type `T` optional. Also, it makes all nested properties optional.
  *
@@ -154,9 +156,9 @@ type OnlyOne<T> = {
  *
  * const obj2: ExampleDeepPartial = { a: { b: 'world' } }; // OK
  */
-type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
-    [P in keyof T]?: DeepPartial<T[P]>;
-}) | T;
+type DeepPartial<T> = T extends NonRecursive ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 /**
  * 將 Obj 指定的 key 轉換成指定的型別
  *

package/dist/cjs/useHorizontalWheel-12s-bwbWVJeM.js

@@ -0,0 +1,47 @@
+'use client';
+var React = require('react');
+
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */ const useHorizontalWheel = ({ speed = 1, respectShiftKey = true } = {})=>{
+    const ref = React.useRef(null);
+    React.useEffect(()=>{
+        const el = ref.current;
+        if (!el) return undefined;
+        const onWheel = (e)=>{
+            if (respectShiftKey && e.shiftKey) return;
+            // deltaY 是「想往下滾」的意圖，我們把它轉成 scrollLeft
+            const delta = e.deltaY * speed;
+            const maxScrollLeft = el.scrollWidth - el.clientWidth;
+            const next = el.scrollLeft + delta;
+            const canScrollHorizontally = el.scrollWidth > el.clientWidth;
+            if (!canScrollHorizontally) return;
+            const willScroll = delta < 0 && el.scrollLeft > 0 || delta > 0 && el.scrollLeft < maxScrollLeft;
+            // 只在「容器還能橫向捲」時攔截，避免卡住頁面垂直捲動
+            if (willScroll) {
+                e.preventDefault();
+                el.scrollLeft = Math.max(0, Math.min(maxScrollLeft, next));
+            }
+        };
+        el.addEventListener('wheel', onWheel, {
+            passive: false
+        });
+        return ()=>el.removeEventListener('wheel', onWheel);
+    }, [
+        speed,
+        respectShiftKey
+    ]);
+    return ref;
+};
+
+exports.useHorizontalWheel = useHorizontalWheel;

package/dist/es/client.d.mts

@@ -1,4 +1,5 @@
-import React, { ReactNode } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
 import { AtLeastOne } from './types.mjs';
 
 type TStoreProps<S> = {
@@ -88,7 +89,7 @@ type TInitialProps$1<S> = TStoreProps<S> & {
  * ```
  */
 declare const createStoreContext: <S>() => {
-    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React.JSX.Element;
+    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React__default.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React__default.JSX.Element;
     useStore: <T>(selector: (state: TStoreState<S>) => T, equalityFn?: (left: T, right: T) => boolean) => T;
 };
 
@@ -121,7 +122,7 @@ type TInitialProps<Q> = Partial<TQueryProps<Q> & {
  *
  * @deprecated use `StoreProvider` from `core/store` instead
  */
-declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.PropsWithChildren<TInitialProps<Q>>) => React.JSX.Element;
+declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React__default.PropsWithChildren<TInitialProps<Q>>) => React__default.JSX.Element;
 /**
  * hook to get the store from the context
  *
@@ -180,7 +181,7 @@ declare const createDataContext: <T>() => {
     readonly DataProvider: ({ children, value }: {
         children: ReactNode;
         value: T;
-    }) => React.JSX.Element;
+    }) => React__default.JSX.Element;
 };
 
 type TCountdownActions = {
@@ -227,6 +228,27 @@ type UseDisclosureReturn = {
  */
 declare function useDisclosure(initialState?: boolean): UseDisclosureReturn;
 
+type Options = {
+    /** 滾輪轉成水平位移的倍率（觸控板通常較小，滑鼠滾輪較大） */
+    speed?: number;
+    /** 是否在按住 Shift 時改走瀏覽器原生（通常 Shift+滾輪就是橫向） */
+    respectShiftKey?: boolean;
+};
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */
+declare const useHorizontalWheel: <T extends HTMLElement>({ speed, respectShiftKey, }?: Options) => React.RefObject<T | null>;
+
 type TValueOptions<T> = AtLeastOne<{
     /**
      * The controlled value.
@@ -250,7 +272,7 @@ type TValueOptions<T> = AtLeastOne<{
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
-declare function mergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;
+declare function mergeRefs<T = any>(refs: Array<React__default.MutableRefObject<T> | React__default.LegacyRef<T> | undefined | null>): React__default.RefCallback<T>;
 
 /**
  * Downloads a file from a given source.
@@ -285,5 +307,5 @@ declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefin
  */
 declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
 
-export { QueryProvider, createDataContext, createStoreContext, downloadFile, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useQueryContext, useValue };
+export { QueryProvider, createDataContext, createStoreContext, downloadFile, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useHorizontalWheel, useQueryContext, useValue };
 export type { TCountdownActions, UseDisclosureReturn };

package/dist/es/client.mjs

@@ -3,6 +3,7 @@ export { Q as QueryProvider, u as useQueryContext } from './queryStore-12s-Dkb-A
 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 { u as useHorizontalWheel } from './useHorizontalWheel-12s-D3IfutV9.mjs';
 export { d as downloadFile } from './download-12s-CnaJ0p_f.mjs';
 export { g as getLocalStorage, s as setLocalStorage } from './webStorage-12s-Bo7x8q5t.mjs';
 

package/dist/es/index.d.mts

@@ -706,6 +706,35 @@ declare function invariant(condition: any, message?: string | (() => string)): a
  */
 declare const isServer: () => boolean;
 
+type MaskKeySelector = string | ((key: string, value: unknown, path: Array<string | number>) => boolean);
+/**
+ * 深度走訪物件/陣列，將指定鍵名且值為字串的欄位遮罩為固定字串（預設 "******"）。
+ *
+ * - 預設僅遮罩鍵名等於 `password` 的欄位（區分大小寫）
+ * - 可傳入「字串鍵名」或「函式選擇器」來自訂要遮罩的欄位
+ * - 僅在值為字串時遮罩，其他型別維持原樣
+ * - 不變更輸入參考；回傳全新的資料結構
+ * - 函式選擇器會收到 `key`、`value` 與 `path`（到該鍵的路徑，陣列用索引）
+ * - 支援巢狀物件與陣列
+ *
+ * @param input - 來源資料
+ * @param mask - 遮罩字串，預設為 "******"
+ * @param selector - 欄位選擇器，字串或函式，預設 'password'
+ * @returns 回傳遮罩後的新資料
+ *
+ * @example
+ * const input = { password: 'secret', user: { password: 'abc' }, list: [{ password: 'x' }, { ok: 1 }] };
+ * const output = maskPasswords(input);
+ * // { password: '******', user: { password: '******' }, list: [{ password: '******' }, { ok: 1 }] }
+ *
+ * // 指定鍵名
+ * maskPasswords({ secret: 'xxx' }, '***', 'secret'); // { secret: '***' }
+ *
+ * // 使用函式選擇器（鍵名包含 'pass' 都遮）
+ * maskPasswords({ password: 'a', passcode: 'b' }, '***', (k) => k.includes('pass')); // { password: '***', passcode: '***' }
+ */
+declare const maskPasswords: <T>(input: T, mask?: string, selector?: MaskKeySelector) => T;
+
 type DeepPartialWithBooleanOverride<T> = {
     [K in keyof T]?: T[K] extends object ? T[K] extends boolean ? T[K] : DeepPartialWithBooleanOverride<T[K]> | boolean : T[K];
 };
@@ -1232,5 +1261,5 @@ declare const generatePeriodArray: () => string[];
  */
 declare const getCurrentPeriod: () => string;
 
-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 };
-export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };
+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, maskPasswords, 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 };
+export type { MaskKeySelector, MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };

package/dist/es/index.mjs

@@ -487,6 +487,74 @@ message) {
  * 判斷執行環境是否為 Server(node.js) 端
  */ const isServer = ()=>typeof window === 'undefined';
 
+/**
+ * 深度走訪物件/陣列，將指定鍵名且值為字串的欄位遮罩為固定字串（預設 "******"）。
+ *
+ * - 預設僅遮罩鍵名等於 `password` 的欄位（區分大小寫）
+ * - 可傳入「字串鍵名」或「函式選擇器」來自訂要遮罩的欄位
+ * - 僅在值為字串時遮罩，其他型別維持原樣
+ * - 不變更輸入參考；回傳全新的資料結構
+ * - 函式選擇器會收到 `key`、`value` 與 `path`（到該鍵的路徑，陣列用索引）
+ * - 支援巢狀物件與陣列
+ *
+ * @param input - 來源資料
+ * @param mask - 遮罩字串，預設為 "******"
+ * @param selector - 欄位選擇器，字串或函式，預設 'password'
+ * @returns 回傳遮罩後的新資料
+ *
+ * @example
+ * const input = { password: 'secret', user: { password: 'abc' }, list: [{ password: 'x' }, { ok: 1 }] };
+ * const output = maskPasswords(input);
+ * // { password: '******', user: { password: '******' }, list: [{ password: '******' }, { ok: 1 }] }
+ *
+ * // 指定鍵名
+ * maskPasswords({ secret: 'xxx' }, '***', 'secret'); // { secret: '***' }
+ *
+ * // 使用函式選擇器（鍵名包含 'pass' 都遮）
+ * maskPasswords({ password: 'a', passcode: 'b' }, '***', (k) => k.includes('pass')); // { password: '***', passcode: '***' }
+ */ const maskPasswords = (input, mask = '******', selector = 'password')=>{
+    const isObject = (val)=>val !== null && typeof val === 'object' && !Array.isArray(val) && !(val instanceof Date);
+    const shouldMask = (key, value, path)=>{
+        if (typeof selector === 'string') {
+            return key === selector && typeof value === 'string';
+        }
+        return selector(key, value, path) && typeof value === 'string';
+    };
+    const walk = (val, path)=>{
+        if (val === null || val === undefined) return val;
+        if (Array.isArray(val)) {
+            return val.map((item, idx)=>walk(item, [
+                    ...path,
+                    idx
+                ]));
+        }
+        if (val instanceof Date) {
+            return new Date(val.getTime());
+        }
+        if (isObject(val)) {
+            const result = Object.entries(val).reduce((acc, [key, v])=>{
+                const nextPath = [
+                    ...path,
+                    key
+                ];
+                if (shouldMask(key, v, nextPath)) {
+                    return {
+                        ...acc,
+                        [key]: mask
+                    };
+                }
+                return {
+                    ...acc,
+                    [key]: walk(v, nextPath)
+                };
+            }, {});
+            return result;
+        }
+        return val;
+    };
+    return walk(input, []);
+};
+
 /**
  * 將物件中的某些 key 排除
  *
@@ -1397,4 +1465,4 @@ const FILE_SIZE_UNITS = [
     return dayjs(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-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 };
+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, maskPasswords, 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/types.d.mts

@@ -137,6 +137,8 @@ type OnlyOne<T> = {
         [P in Exclude<keyof T, K>]?: never;
     };
 }[keyof T];
+type Builtin = string | number | boolean | bigint | symbol | null | undefined;
+type NonRecursive = Builtin | Function | Date | RegExp | Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any> | Promise<any>;
 /**
  * A utility type that makes all properties in the generic type `T` optional. Also, it makes all nested properties optional.
  *
@@ -154,9 +156,9 @@ type OnlyOne<T> = {
  *
  * const obj2: ExampleDeepPartial = { a: { b: 'world' } }; // OK
  */
-type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
-    [P in keyof T]?: DeepPartial<T[P]>;
-}) | T;
+type DeepPartial<T> = T extends NonRecursive ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 /**
  * 將 Obj 指定的 key 轉換成指定的型別
  *

package/dist/es/useHorizontalWheel-12s-D3IfutV9.mjs

@@ -0,0 +1,47 @@
+'use client';
+import { useRef, useEffect } from 'react';
+
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */ const useHorizontalWheel = ({ speed = 1, respectShiftKey = true } = {})=>{
+    const ref = useRef(null);
+    useEffect(()=>{
+        const el = ref.current;
+        if (!el) return undefined;
+        const onWheel = (e)=>{
+            if (respectShiftKey && e.shiftKey) return;
+            // deltaY 是「想往下滾」的意圖，我們把它轉成 scrollLeft
+            const delta = e.deltaY * speed;
+            const maxScrollLeft = el.scrollWidth - el.clientWidth;
+            const next = el.scrollLeft + delta;
+            const canScrollHorizontally = el.scrollWidth > el.clientWidth;
+            if (!canScrollHorizontally) return;
+            const willScroll = delta < 0 && el.scrollLeft > 0 || delta > 0 && el.scrollLeft < maxScrollLeft;
+            // 只在「容器還能橫向捲」時攔截，避免卡住頁面垂直捲動
+            if (willScroll) {
+                e.preventDefault();
+                el.scrollLeft = Math.max(0, Math.min(maxScrollLeft, next));
+            }
+        };
+        el.addEventListener('wheel', onWheel, {
+            passive: false
+        });
+        return ()=>el.removeEventListener('wheel', onWheel);
+    }, [
+        speed,
+        respectShiftKey
+    ]);
+    return ref;
+};
+
+export { useHorizontalWheel as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [