@gateweb/react-utils 2.4.0 → 2.6.0

package/dist/cjs/client.d.ts

@@ -269,6 +269,8 @@ type TValueOptions<T> = AtLeastOne<{
  *    const [currentValue, setCurrentValue] = useValue({ value });
  * };
  * ```
+ *
+ * @deprecated This hook is deprecated in favor of `useControllableState`, which provides more features and better performance. Please use `useControllableState` instead.
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
@@ -286,6 +288,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 +338,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 }; }
@@ -74,6 +74,8 @@ var React__default = /*#__PURE__*/_interopDefault(React);
  *    const [currentValue, setCurrentValue] = useValue({ value });
  * };
  * ```
+ *
+ * @deprecated This hook is deprecated in favor of `useControllableState`, which provides more features and better performance. Please use `useControllableState` instead.
  */ const useValue = ({ value, defaultValue })=>{
     if (value === undefined && defaultValue === undefined) {
         throw new Error('Either `value` or `defaultValue` must be provided.');
@@ -114,6 +116,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

@@ -269,6 +269,8 @@ type TValueOptions<T> = AtLeastOne<{
  *    const [currentValue, setCurrentValue] = useValue({ value });
  * };
  * ```
+ *
+ * @deprecated This hook is deprecated in favor of `useControllableState`, which provides more features and better performance. Please use `useControllableState` instead.
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
@@ -286,6 +288,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 +338,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';
 
 /**
@@ -68,6 +68,8 @@ export { g as getLocalStorage, s as setLocalStorage } from './webStorage-12s-Bo7
  *    const [currentValue, setCurrentValue] = useValue({ value });
  * };
  * ```
+ *
+ * @deprecated This hook is deprecated in favor of `useControllableState`, which provides more features and better performance. Please use `useControllableState` instead.
  */ const useValue = ({ value, defaultValue })=>{
     if (value === undefined && defaultValue === undefined) {
         throw new Error('Either `value` or `defaultValue` must be provided.');

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,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GW-VAT-BPSP-Team/react-utils",
   "repository": {

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 };