@gateweb/react-utils 1.10.0 → 1.11.0

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { ReactNode } from 'react';
 import { AtLeastOne } from './types.js';
 export * from './types.js';
 
@@ -404,6 +404,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * @param obj 要處理的物件
  * @param name 生成的 enum 名稱
+ * @param scene 要使用的條件 (參考 example)
  *
  * @example
  *
@@ -974,6 +975,43 @@ declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.
  */
 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;
@@ -1107,4 +1145,4 @@ 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 PartialBy, QueryProvider, type RequiredBy, type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, 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, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { ByteSize, 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, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };

package/dist/cjs/index.js

@@ -2,14 +2,15 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var dayjs = require('dayjs');
 var queryStoreClient = require('./queryStore-client-q_SLGgYH.js');
-var useCountdownClient = require('./useCountdown-client-uiqhgllY.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');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var dayjs__default = /*#__PURE__*/_interopDefault(dayjs);
+var React__default = /*#__PURE__*/_interopDefault(React);
 
 const FILE_SIZE_UNITS$1 = [
     'Bytes',
@@ -1043,6 +1044,57 @@ const FILE_SIZE_UNITS = [
     return dayjs__default.default(dateString, format, true).isValid();
 };
 
+/**
+ * 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>
+ *   );
+ * }
+ */ const createDataContext = ()=>{
+    const Context = /*#__PURE__*/ React.createContext(undefined);
+    const useDataContext = ()=>{
+        const context = React.useContext(Context);
+        if (context === undefined) {
+            throw new Error(`useDataContext must be used within a DataProvider`);
+        }
+        return context;
+    };
+    const DataProvider = ({ children, value })=>{
+        const memoized = React.useMemo(()=>value, [
+            value
+        ]);
+        return /*#__PURE__*/ React__default.default.createElement(Context.Provider, {
+            value: memoized
+        }, children);
+    };
+    return {
+        useDataContext,
+        DataProvider
+    };
+};
+
 /**
  * A hook to manage a value.
  *
@@ -1180,6 +1232,7 @@ exports.camelCase2SnakeCase = camelCase2SnakeCase;
 exports.camelString2PascalString = camelString2PascalString;
 exports.camelString2SnakeString = camelString2SnakeString;
 exports.convertBytes = convertBytes;
+exports.createDataContext = createDataContext;
 exports.createEnumLikeObject = createEnumLikeObject;
 exports.debounce = debounce;
 exports.deepMerge = deepMerge;

package/dist/es/index.d.mts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { ReactNode } from 'react';
 import { AtLeastOne } from './types.mjs';
 export * from './types.mjs';
 
@@ -404,6 +404,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * @param obj 要處理的物件
  * @param name 生成的 enum 名稱
+ * @param scene 要使用的條件 (參考 example)
  *
  * @example
  *
@@ -974,6 +975,43 @@ declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.
  */
 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;
@@ -1107,4 +1145,4 @@ 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 PartialBy, QueryProvider, type RequiredBy, type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, 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, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { ByteSize, 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, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };

package/dist/es/index.mjs

@@ -1,7 +1,7 @@
 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 { u as useCountdown } from './useCountdown-client-t52WIHfq.mjs';
-import { useState, useCallback } from 'react';
 export { d as downloadFile } from './download-client-CnaJ0p_f.mjs';
 export { g as getLocalStorage, s as setLocalStorage } from './webStorage-client-Pd-loNCg.mjs';
 
@@ -1037,6 +1037,57 @@ const FILE_SIZE_UNITS = [
     return dayjs(dateString, format, true).isValid();
 };
 
+/**
+ * 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>
+ *   );
+ * }
+ */ const createDataContext = ()=>{
+    const Context = /*#__PURE__*/ createContext(undefined);
+    const useDataContext = ()=>{
+        const context = useContext(Context);
+        if (context === undefined) {
+            throw new Error(`useDataContext must be used within a DataProvider`);
+        }
+        return context;
+    };
+    const DataProvider = ({ children, value })=>{
+        const memoized = useMemo(()=>value, [
+            value
+        ]);
+        return /*#__PURE__*/ React.createElement(Context.Provider, {
+            value: memoized
+        }, children);
+    };
+    return {
+        useDataContext,
+        DataProvider
+    };
+};
+
 /**
  * A hook to manage a value.
  *
@@ -1161,4 +1212,4 @@ function mergeRefs(refs) {
     return dayjs(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-export { ByteSize, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, 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, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [
@@ -45,6 +45,7 @@
     "@commitlint/cli": "^19.5.0",
     "@commitlint/config-conventional": "^19.5.0",
     "@gateweb/eslint-config-gateweb": "^1.0.6",
+    "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.2.0",
     "@types/jest": "^29.5.13",
     "@types/node": "^22.7.7",