@gateweb/react-utils 2.2.0 → 2.4.0

package/README.md

@@ -1,6 +1,8 @@
 # @gateweb/react-utils
 
-**`@gateweb/react-utils`** is a comprehensive, TypeScript-first utility library designed to streamline development in React projects at GateWeb. It provides a collection of robust, well-tested, and reusable functions and hooks, covering everything from date manipulation and type conversion to custom hooks and web APIs.
+**`@gateweb/react-utils`** 是 GateWeb 的 TypeScript-first utility library，包含常用的 functions / hooks / types（日期、格式化、轉換、驗證、web、React hooks 等），並且有測試與自動化文件。
+
+> This repo also provides a docs site + auto-generated API reference.
 
 [![npm version](https://img.shields.io/npm/v/@gateweb/react-utils.svg)](https://www.npmjs.com/package/@gateweb/react-utils)
 
@@ -27,95 +29,15 @@ npm install @gateweb/react-utils
 yarn add @gateweb/react-utils
 ```
 
-## 🚀 Usage
-
-Here are some examples of the most common utilities.
-
-### React Hooks
-
-#### `useCountdown`
-
-A hook to manage a countdown timer.
-
-```tsx
-import { useCountdown } from '@gateweb/react-utils';
-
-function MyComponent() {
-  const { count, start, stop, reset } = useCountdown({ initialValue: 60 });
-
-  return (
-    <div>
-      <p>Countdown: {count}</p>
-      <button onClick={start}>Start</button>
-      <button onClick={stop}>Stop</button>
-      <button onClick={reset}>Reset</button>
-    </div>
-  );
-}
-```
-
-### Date Utilities
-
-#### `formatDate`
-
-Format a date object or string into a custom format.
-
-```ts
-import { formatDate } from '@gateweb/react-utils';
-
-const formattedDate = formatDate(new Date(), 'YYYY-MM-DD');
-console.log(formattedDate); // e.g., "2023-10-27"
-```
-
-#### `getPeriod`
-
-Get a predefined date period, like "last 7 days".
-
-```ts
-import { getPeriod } from '@gateweb/react-utils';
-
-const last7Days = getPeriod('last_7_days');
-console.log(last7Days); // { startDate: Dayjs, endDate: Dayjs }
-```
-
-### Core Utilities
-
-#### `toCamelCase`
-
-Convert a string from snake_case or kebab-case to camelCase.
-
-```ts
-import { toCamelCase } from '@gateweb/react-utils';
-
-const camel = toCamelCase('hello_world-example');
-console.log(camel); // "helloWorldExample"
-```
-
-#### `bytesToSize`
-
-Convert bytes to a human-readable format (KB, MB, GB).
+## 🚀 快速開始（Quick Start）
 
 ```ts
 import { bytesToSize } from '@gateweb/react-utils';
 
-const size = bytesToSize(1024 * 1024 * 5); // 5MB
-console.log(size); // "5 MB"
+bytesToSize(1024);
 ```
 
-### Web APIs
-
-#### `download`
-
-A simple utility to trigger a file download in the browser.
-
-```ts
-import { download } from '@gateweb/react-utils';
-
-function handleDownload() {
-  const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
-  download(blob, 'hello.txt');
-}
-```
+更多範例與用法請看 [react-utils docs](https://crispy-dollop-o765k9n.pages.github.io/)
 
 ## 🤝 Contributing
 

package/dist/cjs/index.d.ts

@@ -463,14 +463,14 @@ type ScenesList<T extends Record<string, {
 type NormalReturn<T extends Record<string, any>, VK extends string> = {
     Enum: EnumMap<T, VK>;
     List: NormalList<T>;
-    getLabel: (value: ValueAtKey<T, VK>) => string;
+    getLabel: (value: ValueAtKey<T, VK>, keep?: boolean) => string | undefined;
 };
 type ScenesReturn<T extends Record<string, {
     scenes: Record<string, Record<string, any>>;
 }>, Scene extends keyof T[keyof T]['scenes'] & string, VK extends string> = {
     Enum: EnumMap<T, VK>;
     List: ScenesList<T, Scene, VK>;
-    getLabel: (value: ValueAtKey<T, VK>) => string;
+    getLabel: (value: ValueAtKey<T, VK>, keep?: boolean) => string | undefined;
 };
 type AsNamed<R, N extends string> = {
     [K in keyof R as K extends 'Enum' ? `Enum${N}` : K extends 'List' ? `${N}List` : K extends 'getLabel' ? `get${N}Label` : never]: R[K];

package/dist/cjs/index.js

@@ -274,9 +274,10 @@ function createEnumLikeObject(obj, options) {
                 ...item
             }));
     }
-    function getLabel(value) {
+    function getLabel(value, keep = true) {
         const targetItem = list.find((item)=>// 如果 list 項目內含有 valueKey 對應欄位，優先以該欄位比對；否則以 value 欄位比對
             valueKey in item ? item[valueKey] === value : item.value === value);
+        if (!targetItem && !keep) return undefined;
         if (!targetItem) return String(value);
         if ('label' in targetItem) return targetItem.label;
         return String(value);

package/dist/es/index.d.mts

@@ -463,14 +463,14 @@ type ScenesList<T extends Record<string, {
 type NormalReturn<T extends Record<string, any>, VK extends string> = {
     Enum: EnumMap<T, VK>;
     List: NormalList<T>;
-    getLabel: (value: ValueAtKey<T, VK>) => string;
+    getLabel: (value: ValueAtKey<T, VK>, keep?: boolean) => string | undefined;
 };
 type ScenesReturn<T extends Record<string, {
     scenes: Record<string, Record<string, any>>;
 }>, Scene extends keyof T[keyof T]['scenes'] & string, VK extends string> = {
     Enum: EnumMap<T, VK>;
     List: ScenesList<T, Scene, VK>;
-    getLabel: (value: ValueAtKey<T, VK>) => string;
+    getLabel: (value: ValueAtKey<T, VK>, keep?: boolean) => string | undefined;
 };
 type AsNamed<R, N extends string> = {
     [K in keyof R as K extends 'Enum' ? `Enum${N}` : K extends 'List' ? `${N}List` : K extends 'getLabel' ? `get${N}Label` : never]: R[K];

package/dist/es/index.mjs

@@ -268,9 +268,10 @@ function createEnumLikeObject(obj, options) {
                 ...item
             }));
     }
-    function getLabel(value) {
+    function getLabel(value, keep = true) {
         const targetItem = list.find((item)=>// 如果 list 項目內含有 valueKey 對應欄位，優先以該欄位比對；否則以 value 欄位比對
             valueKey in item ? item[valueKey] === value : item.value === value);
+        if (!targetItem && !keep) return undefined;
         if (!targetItem) return String(value);
         if ('label' in targetItem) return targetItem.label;
         return String(value);

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "React Utils for GateWeb",
-  "homepage": "https://github.com/GatewebSolutions/react-utils",
+  "homepage": "https://github.com/GW-VAT-BPSP-Team/react-utils",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GW-VAT-BPSP-Team/react-utils.git"
+  },
   "files": [
     "dist"
   ],
@@ -69,9 +73,12 @@
     "jest-environment-jsdom": "^30.0.5",
     "lint-staged": "^16.1.2",
     "prettier": "^3.6.2",
+    "typedoc": "^0.28.0",
+    "typedoc-plugin-markdown": "^4.8.0",
     "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3",
+    "vitepress": "^1.6.3",
     "vitest": "^3.2.4"
   },
   "commitlint": {
@@ -86,6 +93,13 @@
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui --coverage.enabled=true",
     "build": "bunchee",
-    "build:prepare": "bunchee --prepare"
+    "build:prepare": "bunchee --prepare",
+    "api-docs:main": "typedoc --options typedoc.base.json --out docs/api/main src/index.ts && node scripts/generate-api-file-pages.js main",
+    "api-docs:client": "typedoc --options typedoc.base.json --out docs/api/client src/client.ts && node scripts/generate-api-file-pages.js client",
+    "api-docs:types": "typedoc --options typedoc.base.json --out docs/api/types src/types/index.ts && node scripts/generate-api-file-pages.js types",
+    "api-docs:build": "pnpm api-docs:main && pnpm api-docs:client && pnpm api-docs:types",
+    "docs:dev": "pnpm api-docs:build && vitepress dev docs",
+    "docs:build": "pnpm api-docs:build && vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }