@gateweb/react-utils 1.17.0 → 2.1.0

package/dist/es/index.d.mts

@@ -1,5 +1,3 @@
-import React, { ReactNode } from 'react';
-import { AtLeastOne } from './types.mjs';
 export * from './types.mjs';
 
 /**
@@ -708,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];
 };
@@ -1183,162 +1210,6 @@ declare const validateDateString: (dateString: string, format: string) => boolea
  */
 declare const isNil: (value: unknown) => value is null | undefined;
 
-type TQueryProps<Q> = {
-    /**
-     * the query object
-     */
-    query: Partial<Q>;
-};
-type TQueryState<Q> = {
-    /**
-     * trigger the change of query
-     *
-     * @param query - the new query
-     */
-    changeQuery: (query: TQueryProps<Q>['query']) => void;
-} & TQueryProps<Q>;
-type TInitialProps<Q> = Partial<TQueryProps<Q> & {
-    /**
-     * handle the change of query when calling `changeQuery`
-     *
-     * @param preQuery - the previous query
-     * @param newQuery - the new query
-     * @returns the custom new query
-     */
-    handleChangeQuery: (preQuery: TQueryProps<Q>['query'], newQuery: TQueryProps<Q>['query']) => TQueryProps<Q>['query'];
-}>;
-/**
- * Provider to provide the store to the context
- */
-declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.PropsWithChildren<TInitialProps<Q>>) => React.JSX.Element;
-/**
- * hook to get the store from the context
- *
- * because we want the return type of `selector` to be inferred by ts, we use HOF to implement the hook
- *
- * so you should use it like this:
- *
- * ```tsx
- * const useQuery = useQueryContext<MyObject>(); // => will return the store hook
- * const result = useQuery(q => q.query); // => will return the query object
- * ```
- *
- * @example
- *
- * ```tsx
- * const result1 = useQueryContext<MyObject>()(q => '1234');
- * const result2 = useQueryContext<MyObject>()(q => q.changeQuery);
- * const result3 = useQueryContext<MyObject>()(q => q.query);
- * ```
- */
-declare const useQueryContext: <Q>() => <T>(selector: (state: TQueryState<Q>) => T, equalityFn?: (left: T, right: T) => boolean) => T;
-
-/**
- * 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>
- *   );
- * }
- */
-declare const createDataContext: <T>() => {
-    readonly useDataContext: () => T & ({} | null);
-    readonly DataProvider: ({ children, value }: {
-        children: ReactNode;
-        value: T;
-    }) => React.JSX.Element;
-};
-
-type TCountdownActions = {
-    /** 目前秒數 */
-    countdown: number;
-    /** 是否正在倒數計時 */
-    isCounting: boolean;
-    /** 開始倒數計時 */
-    start: () => void;
-    /** 停止倒數計時 */
-    stop: () => void;
-    /** 重置倒數計時 */
-    reset: () => void;
-};
-/**
- * 倒數計時器
- *
- * 可以透過 start() 來啟動倒數計時器
- * 可以透過 stop() 來停止倒數計時器
- * 可以透過 reset() 來重置倒數計時器
- *
- * @param initialCountdown 倒數計時器初始值
- * @param enableReinitialize 允許重設初始值
- */
-declare const useCountdown: (initialCountdown: number, enableReinitialize?: boolean) => TCountdownActions;
-
-type UseDisclosureReturn = {
-    /** Whether the disclosure is currently open. */
-    isOpen: boolean;
-    /** Open the disclosure (sets isOpen = true). */
-    open: () => void;
-    /** Close the disclosure (sets isOpen = false). */
-    close: () => void;
-    /** Toggle the disclosure state (open -> close or close -> open). */
-    toggle: () => void;
-};
-/**
- * A small hook to control open/close state.
- *
- * Supports an optional controlled pattern by passing `isOpen` and `onChange`.
- *
- * @example
- * const { isOpen, open, close, toggle } = useDisclosure();
- */
-declare function useDisclosure(initialState?: boolean): UseDisclosureReturn;
-
-type TValueOptions<T> = AtLeastOne<{
-    /**
-     * The controlled value.
-     */
-    value?: T;
-    /**
-     * The default value.
-     */
-    defaultValue?: T;
-}>;
-/**
- * A hook to manage a value.
- *
- * @example
- *
- * ```tsx
- * const MyComponent = ({ value }: { value?: number }) => {
- *    const [currentValue, setCurrentValue] = useValue({ value });
- * };
- * ```
- */
-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>;
-
 /**
  * 民國年轉西元年
  * @param dateString 日期字串
@@ -1390,38 +1261,5 @@ declare const generatePeriodArray: () => string[];
  */
 declare const getCurrentPeriod: () => string;
 
-/**
- * Downloads a file from a given source.
- *
- * @param source - The source of the file to be downloaded. It can be a URL string or a Blob object.
- * @param filename - The name of the file to be downloaded. Defaults to the current timestamp if not provided.
- * @param fileExtension - The file extension to be appended to the filename. Optional.
- *
- * @example
- * downloadFile('http://example.com/file.txt', 'testfile', 'txt');
- * downloadFile(new Blob(['test content'], { type: 'text/plain' }), 'testfile', 'txt');
- */
-declare const downloadFile: (source: string | Blob, filename?: string, fileExtension?: string) => void;
-
-/**
- * 從 localStorage 取得資料，支援槽狀取值(Json 物件)
- *
- * @param key 鍵值
- * @param deCode 是否解碼
- * @returns 取得的資料
- * @example
- * const data = getLocalStorage('key');
- *
- * const data = getLocalStorage('key.subKey');
- */
-declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefined;
-/**
- * 將資料(Json 物件)存入 localStorage
- * @param key 鍵值
- * @param value 可序列化的資料
- * @param enCode 是否編碼
- */
-declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
-
-export { ByteSize, MimeTypeMap, OtherMimeType, QueryProvider, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, decodeBase64, decodeJson, deepClone, deepMerge, downloadFile, encodeBase64, encodeJson, 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, renameKey, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useDisclosure, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
-export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy, TCountdownActions, UseDisclosureReturn };
+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 };