@gateweb/react-utils 2.3.0 → 2.5.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/client.d.ts

@@ -286,6 +286,35 @@ declare function mergeRefs<T = any>(refs: Array<React__default.MutableRefObject<
  * downloadFile(new Blob(['test content'], { type: 'text/plain' }), 'testfile', 'txt');
  */
 declare const downloadFile: (source: string | Blob, filename?: string, fileExtension?: string) => void;
+type DownloadFileOptions = {
+    /**
+     * The url string to download.
+     */
+    url: string;
+    /**
+     * The filename to use for the downloaded file (without extension)
+     *
+     * @default The current timestamp as a string (e.g. "1686789123456")
+     */
+    filename?: string;
+    /**
+     * The file extension to append to the filename (e.g. "txt", "pdf").
+     */
+    fileExtension?: string;
+    /**
+     * `fetch` init options (e.g. `credentials`, `headers`).
+     *
+     * Note: the URL must allow CORS (or be same-origin) for the browser to read the response.
+     */
+    fetchInit?: RequestInit;
+};
+/**
+ * Downloads a file by fetching the URL into a Blob first, then triggering a blob download.
+ *
+ * This is useful when a URL returns a previewable Content-Type (e.g. `application/pdf`) and
+ * the browser would otherwise open a new tab to preview instead of downloading.
+ */
+declare const downloadFileWithFetch: ({ url, filename, fileExtension, fetchInit, }: DownloadFileOptions) => Promise<void>;
 
 /**
  * 從 localStorage 取得資料，支援槽狀取值(Json 物件)
@@ -307,5 +336,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, useHorizontalWheel, useQueryContext, useValue };
-export type { TCountdownActions, UseDisclosureReturn };
+export { QueryProvider, createDataContext, createStoreContext, downloadFile, downloadFileWithFetch, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useHorizontalWheel, useQueryContext, useValue };
+export type { DownloadFileOptions, TCountdownActions, UseDisclosureReturn };

package/dist/cjs/client.js

@@ -6,7 +6,7 @@ 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 download12s = require('./download-12s-C5yIKqRX.js');
 var webStorage12s = require('./webStorage-12s-0RtNO_uc.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -114,6 +114,7 @@ exports.useCountdown = useCountdown12s.useCountdown;
 exports.useDisclosure = useDisclosure12s.useDisclosure;
 exports.useHorizontalWheel = useHorizontalWheel12s.useHorizontalWheel;
 exports.downloadFile = download12s.downloadFile;
+exports.downloadFileWithFetch = download12s.downloadFileWithFetch;
 exports.getLocalStorage = webStorage12s.getLocalStorage;
 exports.setLocalStorage = webStorage12s.setLocalStorage;
 exports.createDataContext = createDataContext;

package/dist/cjs/download-12s-C5yIKqRX.js

@@ -0,0 +1,65 @@
+'use client';
+const sanitizeUrlForError = (input)=>{
+    try {
+        const parsed = new URL(input);
+        return `${parsed.origin}${parsed.pathname}`;
+    } catch  {
+        return input.split('#')[0].split('?')[0];
+    }
+};
+/**
+ * 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');
+ */ const downloadFile = (source, filename = new Date().getTime().toString(), fileExtension)=>{
+    const shouldRevokeObjectUrl = typeof source !== 'string';
+    const url = shouldRevokeObjectUrl ? URL.createObjectURL(source) : source;
+    const link = document.createElement('a');
+    link.id = `download-${new Date().getTime()}`;
+    document.body.appendChild(link);
+    if (!fileExtension) {
+        link.download = filename;
+    } else {
+        link.download = `${filename}.${fileExtension}`;
+    }
+    link.href = url;
+    link.target = '_blank';
+    link.click();
+    link.remove();
+    if (shouldRevokeObjectUrl) {
+        // Defer revocation to avoid interfering with the download in some browsers.
+        setTimeout(()=>{
+            URL.revokeObjectURL(url);
+        }, 0);
+    }
+};
+/**
+ * Downloads a file by fetching the URL into a Blob first, then triggering a blob download.
+ *
+ * This is useful when a URL returns a previewable Content-Type (e.g. `application/pdf`) and
+ * the browser would otherwise open a new tab to preview instead of downloading.
+ */ const downloadFileWithFetch = async ({ url, filename = new Date().getTime().toString(), fileExtension, fetchInit })=>{
+    const safeUrl = sanitizeUrlForError(url);
+    let response;
+    try {
+        response = await fetch(url, fetchInit);
+    } catch (error) {
+        throw new Error(`downloadFileWithFetch: fetch failed for ${safeUrl}`, {
+            cause: error
+        });
+    }
+    if (!response.ok) {
+        throw new Error(`downloadFileWithFetch: failed to fetch ${safeUrl} (status ${response.status} ${response.statusText})`);
+    }
+    const blob = await response.blob();
+    downloadFile(blob, filename, fileExtension);
+};
+
+exports.downloadFile = downloadFile;
+exports.downloadFileWithFetch = downloadFileWithFetch;

package/dist/es/client.d.mts

@@ -286,6 +286,35 @@ declare function mergeRefs<T = any>(refs: Array<React__default.MutableRefObject<
  * downloadFile(new Blob(['test content'], { type: 'text/plain' }), 'testfile', 'txt');
  */
 declare const downloadFile: (source: string | Blob, filename?: string, fileExtension?: string) => void;
+type DownloadFileOptions = {
+    /**
+     * The url string to download.
+     */
+    url: string;
+    /**
+     * The filename to use for the downloaded file (without extension)
+     *
+     * @default The current timestamp as a string (e.g. "1686789123456")
+     */
+    filename?: string;
+    /**
+     * The file extension to append to the filename (e.g. "txt", "pdf").
+     */
+    fileExtension?: string;
+    /**
+     * `fetch` init options (e.g. `credentials`, `headers`).
+     *
+     * Note: the URL must allow CORS (or be same-origin) for the browser to read the response.
+     */
+    fetchInit?: RequestInit;
+};
+/**
+ * Downloads a file by fetching the URL into a Blob first, then triggering a blob download.
+ *
+ * This is useful when a URL returns a previewable Content-Type (e.g. `application/pdf`) and
+ * the browser would otherwise open a new tab to preview instead of downloading.
+ */
+declare const downloadFileWithFetch: ({ url, filename, fileExtension, fetchInit, }: DownloadFileOptions) => Promise<void>;
 
 /**
  * 從 localStorage 取得資料，支援槽狀取值(Json 物件)
@@ -307,5 +336,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, useHorizontalWheel, useQueryContext, useValue };
-export type { TCountdownActions, UseDisclosureReturn };
+export { QueryProvider, createDataContext, createStoreContext, downloadFile, downloadFileWithFetch, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useHorizontalWheel, useQueryContext, useValue };
+export type { DownloadFileOptions, TCountdownActions, UseDisclosureReturn };

package/dist/es/client.mjs

@@ -4,7 +4,7 @@ import React, { useMemo, createContext, useContext, useState, useCallback } from
 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 { d as downloadFile, a as downloadFileWithFetch } from './download-12s-DtxLfLpr.mjs';
 export { g as getLocalStorage, s as setLocalStorage } from './webStorage-12s-Bo7x8q5t.mjs';
 
 /**

package/dist/es/download-12s-DtxLfLpr.mjs

@@ -0,0 +1,64 @@
+'use client';
+const sanitizeUrlForError = (input)=>{
+    try {
+        const parsed = new URL(input);
+        return `${parsed.origin}${parsed.pathname}`;
+    } catch  {
+        return input.split('#')[0].split('?')[0];
+    }
+};
+/**
+ * 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');
+ */ const downloadFile = (source, filename = new Date().getTime().toString(), fileExtension)=>{
+    const shouldRevokeObjectUrl = typeof source !== 'string';
+    const url = shouldRevokeObjectUrl ? URL.createObjectURL(source) : source;
+    const link = document.createElement('a');
+    link.id = `download-${new Date().getTime()}`;
+    document.body.appendChild(link);
+    if (!fileExtension) {
+        link.download = filename;
+    } else {
+        link.download = `${filename}.${fileExtension}`;
+    }
+    link.href = url;
+    link.target = '_blank';
+    link.click();
+    link.remove();
+    if (shouldRevokeObjectUrl) {
+        // Defer revocation to avoid interfering with the download in some browsers.
+        setTimeout(()=>{
+            URL.revokeObjectURL(url);
+        }, 0);
+    }
+};
+/**
+ * Downloads a file by fetching the URL into a Blob first, then triggering a blob download.
+ *
+ * This is useful when a URL returns a previewable Content-Type (e.g. `application/pdf`) and
+ * the browser would otherwise open a new tab to preview instead of downloading.
+ */ const downloadFileWithFetch = async ({ url, filename = new Date().getTime().toString(), fileExtension, fetchInit })=>{
+    const safeUrl = sanitizeUrlForError(url);
+    let response;
+    try {
+        response = await fetch(url, fetchInit);
+    } catch (error) {
+        throw new Error(`downloadFileWithFetch: fetch failed for ${safeUrl}`, {
+            cause: error
+        });
+    }
+    if (!response.ok) {
+        throw new Error(`downloadFileWithFetch: failed to fetch ${safeUrl} (status ${response.status} ${response.statusText})`);
+    }
+    const blob = await response.blob();
+    downloadFile(blob, filename, fileExtension);
+};
+
+export { downloadFileWithFetch as a, downloadFile as d };

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "2.3.0",
+  "version": "2.5.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"
   }
 }

package/dist/cjs/download-12s-DKxkL92w.js

@@ -1,27 +0,0 @@
-'use client';
-/**
- * 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');
- */ const downloadFile = (source, filename = new Date().getTime().toString(), fileExtension)=>{
-    const url = typeof source === 'string' ? source : URL.createObjectURL(source);
-    const link = document.createElement('a');
-    link.id = `download-${new Date().getTime()}`;
-    document.body.appendChild(link);
-    if (!fileExtension) {
-        link.download = filename;
-    } else {
-        link.download = `${filename}.${fileExtension}`;
-    }
-    link.href = url;
-    link.target = '_blank';
-    link.click();
-};
-
-exports.downloadFile = downloadFile;

package/dist/es/download-12s-CnaJ0p_f.mjs

@@ -1,27 +0,0 @@
-'use client';
-/**
- * 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');
- */ const downloadFile = (source, filename = new Date().getTime().toString(), fileExtension)=>{
-    const url = typeof source === 'string' ? source : URL.createObjectURL(source);
-    const link = document.createElement('a');
-    link.id = `download-${new Date().getTime()}`;
-    document.body.appendChild(link);
-    if (!fileExtension) {
-        link.download = filename;
-    } else {
-        link.download = `${filename}.${fileExtension}`;
-    }
-    link.href = url;
-    link.target = '_blank';
-    link.click();
-};
-
-export { downloadFile as d };