@gateweb/react-utils 1.15.0 → 1.17.0

package/dist/es/index.d.mts

@@ -2,6 +2,74 @@ import React, { ReactNode } from 'react';
 import { AtLeastOne } from './types.mjs';
 export * from './types.mjs';
 
+/**
+ * 將位元組陣列編碼為 base64 字串
+ *
+ * @param bytes 要編碼的位元組陣列
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const bytes = new TextEncoder().encode('Hello World');
+ * const encoded = encodeBase64(bytes);
+ * console.log(encoded); // 'SGVsbG8gV29ybGQ='
+ * ```
+ */
+declare const encodeBase64: (bytes: Uint8Array) => string;
+/**
+ * 將 base64 字串解碼為位元組陣列
+ *
+ * @param base64 要解碼的 base64 字串（支援 base64url 格式）
+ * @returns 解碼後的位元組陣列
+ *
+ * @example
+ * ```ts
+ * const decoded = decodeBase64('SGVsbG8gV29ybGQ=');
+ * const text = new TextDecoder().decode(decoded);
+ * console.log(text); // 'Hello World'
+ * ```
+ */
+declare const decodeBase64: (base64: string) => Uint8Array;
+/**
+ * JSON 可序列化的資料類型
+ */
+type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
+    [key: string]: JsonSerializable;
+};
+/**
+ * 將 JSON 資料編碼為 base64 字串
+ *
+ * @param data 要編碼的 JSON 可序列化資料
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const data = { name: 'John', age: 30 };
+ * const encoded = encodeJson(data);
+ * console.log(encoded); // 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9'
+ *
+ * const array = [1, 2, 3];
+ * const encodedArray = encodeJson(array);
+ * ```
+ */
+declare const encodeJson: <T extends JsonSerializable>(data: T) => string;
+/**
+ * 將 base64 字串解碼為 JSON 資料
+ *
+ * @param b64 要解碼的 base64 字串
+ * @returns 解碼後的資料
+ *
+ * @example
+ * ```ts
+ * const encoded = 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9';
+ * const decoded = decodeJson<{ name: string; age: number }>(encoded);
+ * console.log(decoded); // { name: 'John', age: 30 }
+ *
+ * const decodedArray = decodeJson<number[]>(encodedArray);
+ * ```
+ */
+declare const decodeJson: <T extends JsonSerializable>(b64: string) => T;
+
 declare const FILE_SIZE_UNITS: readonly ["Bytes", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];
 type FileSizeUnit = (typeof FILE_SIZE_UNITS)[number];
 /**
@@ -1226,6 +1294,26 @@ type TCountdownActions = {
  */
 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.
@@ -1316,7 +1404,7 @@ declare const getCurrentPeriod: () => string;
 declare const downloadFile: (source: string | Blob, filename?: string, fileExtension?: string) => void;
 
 /**
- * 從 localStorage 取得資料，支援槽狀取值
+ * 從 localStorage 取得資料，支援槽狀取值(Json 物件)
  *
  * @param key 鍵值
  * @param deCode 是否解碼
@@ -1328,12 +1416,12 @@ declare const downloadFile: (source: string | Blob, filename?: string, fileExten
  */
 declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefined;
 /**
- * 將資料存入 localStorage
+ * 將資料(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, 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, renameKey, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
-export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy, TCountdownActions };
+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 };