@gateweb/react-utils 2.1.0 → 2.3.0

package/dist/cjs/client.d.ts

@@ -1,4 +1,5 @@
-import React, { ReactNode } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
 import { AtLeastOne } from './types.js';
 
 type TStoreProps<S> = {
@@ -88,7 +89,7 @@ type TInitialProps$1<S> = TStoreProps<S> & {
  * ```
  */
 declare const createStoreContext: <S>() => {
-    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React.JSX.Element;
+    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React__default.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React__default.JSX.Element;
     useStore: <T>(selector: (state: TStoreState<S>) => T, equalityFn?: (left: T, right: T) => boolean) => T;
 };
 
@@ -121,7 +122,7 @@ type TInitialProps<Q> = Partial<TQueryProps<Q> & {
  *
  * @deprecated use `StoreProvider` from `core/store` instead
  */
-declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.PropsWithChildren<TInitialProps<Q>>) => React.JSX.Element;
+declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React__default.PropsWithChildren<TInitialProps<Q>>) => React__default.JSX.Element;
 /**
  * hook to get the store from the context
  *
@@ -180,7 +181,7 @@ declare const createDataContext: <T>() => {
     readonly DataProvider: ({ children, value }: {
         children: ReactNode;
         value: T;
-    }) => React.JSX.Element;
+    }) => React__default.JSX.Element;
 };
 
 type TCountdownActions = {
@@ -227,6 +228,27 @@ type UseDisclosureReturn = {
  */
 declare function useDisclosure(initialState?: boolean): UseDisclosureReturn;
 
+type Options = {
+    /** 滾輪轉成水平位移的倍率（觸控板通常較小，滑鼠滾輪較大） */
+    speed?: number;
+    /** 是否在按住 Shift 時改走瀏覽器原生（通常 Shift+滾輪就是橫向） */
+    respectShiftKey?: boolean;
+};
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */
+declare const useHorizontalWheel: <T extends HTMLElement>({ speed, respectShiftKey, }?: Options) => React.RefObject<T | null>;
+
 type TValueOptions<T> = AtLeastOne<{
     /**
      * The controlled value.
@@ -250,7 +272,7 @@ type TValueOptions<T> = AtLeastOne<{
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
-declare function mergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;
+declare function mergeRefs<T = any>(refs: Array<React__default.MutableRefObject<T> | React__default.LegacyRef<T> | undefined | null>): React__default.RefCallback<T>;
 
 /**
  * Downloads a file from a given source.
@@ -285,5 +307,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, useQueryContext, useValue };
+export { QueryProvider, createDataContext, createStoreContext, downloadFile, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useHorizontalWheel, useQueryContext, useValue };
 export type { TCountdownActions, UseDisclosureReturn };

package/dist/cjs/client.js

@@ -5,6 +5,7 @@ var queryStore12s = require('./queryStore-12s-JzzXvjJC.js');
 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 webStorage12s = require('./webStorage-12s-0RtNO_uc.js');
 
@@ -111,6 +112,7 @@ exports.QueryProvider = queryStore12s.QueryProvider;
 exports.useQueryContext = queryStore12s.useQueryContext;
 exports.useCountdown = useCountdown12s.useCountdown;
 exports.useDisclosure = useDisclosure12s.useDisclosure;
+exports.useHorizontalWheel = useHorizontalWheel12s.useHorizontalWheel;
 exports.downloadFile = download12s.downloadFile;
 exports.getLocalStorage = webStorage12s.getLocalStorage;
 exports.setLocalStorage = webStorage12s.setLocalStorage;

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/cjs/types.d.ts

@@ -137,6 +137,8 @@ type OnlyOne<T> = {
         [P in Exclude<keyof T, K>]?: never;
     };
 }[keyof T];
+type Builtin = string | number | boolean | bigint | symbol | null | undefined;
+type NonRecursive = Builtin | Function | Date | RegExp | Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any> | Promise<any>;
 /**
  * A utility type that makes all properties in the generic type `T` optional. Also, it makes all nested properties optional.
  *
@@ -154,9 +156,9 @@ type OnlyOne<T> = {
  *
  * const obj2: ExampleDeepPartial = { a: { b: 'world' } }; // OK
  */
-type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
-    [P in keyof T]?: DeepPartial<T[P]>;
-}) | T;
+type DeepPartial<T> = T extends NonRecursive ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 /**
  * 將 Obj 指定的 key 轉換成指定的型別
  *

package/dist/cjs/useHorizontalWheel-12s-bwbWVJeM.js

@@ -0,0 +1,47 @@
+'use client';
+var React = require('react');
+
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */ const useHorizontalWheel = ({ speed = 1, respectShiftKey = true } = {})=>{
+    const ref = React.useRef(null);
+    React.useEffect(()=>{
+        const el = ref.current;
+        if (!el) return undefined;
+        const onWheel = (e)=>{
+            if (respectShiftKey && e.shiftKey) return;
+            // deltaY 是「想往下滾」的意圖，我們把它轉成 scrollLeft
+            const delta = e.deltaY * speed;
+            const maxScrollLeft = el.scrollWidth - el.clientWidth;
+            const next = el.scrollLeft + delta;
+            const canScrollHorizontally = el.scrollWidth > el.clientWidth;
+            if (!canScrollHorizontally) return;
+            const willScroll = delta < 0 && el.scrollLeft > 0 || delta > 0 && el.scrollLeft < maxScrollLeft;
+            // 只在「容器還能橫向捲」時攔截，避免卡住頁面垂直捲動
+            if (willScroll) {
+                e.preventDefault();
+                el.scrollLeft = Math.max(0, Math.min(maxScrollLeft, next));
+            }
+        };
+        el.addEventListener('wheel', onWheel, {
+            passive: false
+        });
+        return ()=>el.removeEventListener('wheel', onWheel);
+    }, [
+        speed,
+        respectShiftKey
+    ]);
+    return ref;
+};
+
+exports.useHorizontalWheel = useHorizontalWheel;

package/dist/es/client.d.mts

@@ -1,4 +1,5 @@
-import React, { ReactNode } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
 import { AtLeastOne } from './types.mjs';
 
 type TStoreProps<S> = {
@@ -88,7 +89,7 @@ type TInitialProps$1<S> = TStoreProps<S> & {
  * ```
  */
 declare const createStoreContext: <S>() => {
-    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React.JSX.Element;
+    StoreProvider: ({ children, store, handleChangeStore, defaultMerge, }: React__default.PropsWithChildren<Partial<TInitialProps$1<S>>>) => React__default.JSX.Element;
     useStore: <T>(selector: (state: TStoreState<S>) => T, equalityFn?: (left: T, right: T) => boolean) => T;
 };
 
@@ -121,7 +122,7 @@ type TInitialProps<Q> = Partial<TQueryProps<Q> & {
  *
  * @deprecated use `StoreProvider` from `core/store` instead
  */
-declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.PropsWithChildren<TInitialProps<Q>>) => React.JSX.Element;
+declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React__default.PropsWithChildren<TInitialProps<Q>>) => React__default.JSX.Element;
 /**
  * hook to get the store from the context
  *
@@ -180,7 +181,7 @@ declare const createDataContext: <T>() => {
     readonly DataProvider: ({ children, value }: {
         children: ReactNode;
         value: T;
-    }) => React.JSX.Element;
+    }) => React__default.JSX.Element;
 };
 
 type TCountdownActions = {
@@ -227,6 +228,27 @@ type UseDisclosureReturn = {
  */
 declare function useDisclosure(initialState?: boolean): UseDisclosureReturn;
 
+type Options = {
+    /** 滾輪轉成水平位移的倍率（觸控板通常較小，滑鼠滾輪較大） */
+    speed?: number;
+    /** 是否在按住 Shift 時改走瀏覽器原生（通常 Shift+滾輪就是橫向） */
+    respectShiftKey?: boolean;
+};
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */
+declare const useHorizontalWheel: <T extends HTMLElement>({ speed, respectShiftKey, }?: Options) => React.RefObject<T | null>;
+
 type TValueOptions<T> = AtLeastOne<{
     /**
      * The controlled value.
@@ -250,7 +272,7 @@ type TValueOptions<T> = AtLeastOne<{
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
-declare function mergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;
+declare function mergeRefs<T = any>(refs: Array<React__default.MutableRefObject<T> | React__default.LegacyRef<T> | undefined | null>): React__default.RefCallback<T>;
 
 /**
  * Downloads a file from a given source.
@@ -285,5 +307,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, useQueryContext, useValue };
+export { QueryProvider, createDataContext, createStoreContext, downloadFile, getLocalStorage, mergeRefs, setLocalStorage, useCountdown, useDisclosure, useHorizontalWheel, useQueryContext, useValue };
 export type { TCountdownActions, UseDisclosureReturn };

package/dist/es/client.mjs

@@ -3,6 +3,7 @@ export { Q as QueryProvider, u as useQueryContext } from './queryStore-12s-Dkb-A
 import React, { useMemo, createContext, useContext, useState, useCallback } from 'react';
 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 { g as getLocalStorage, s as setLocalStorage } from './webStorage-12s-Bo7x8q5t.mjs';
 

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/dist/es/types.d.mts

@@ -137,6 +137,8 @@ type OnlyOne<T> = {
         [P in Exclude<keyof T, K>]?: never;
     };
 }[keyof T];
+type Builtin = string | number | boolean | bigint | symbol | null | undefined;
+type NonRecursive = Builtin | Function | Date | RegExp | Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any> | Promise<any>;
 /**
  * A utility type that makes all properties in the generic type `T` optional. Also, it makes all nested properties optional.
  *
@@ -154,9 +156,9 @@ type OnlyOne<T> = {
  *
  * const obj2: ExampleDeepPartial = { a: { b: 'world' } }; // OK
  */
-type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
-    [P in keyof T]?: DeepPartial<T[P]>;
-}) | T;
+type DeepPartial<T> = T extends NonRecursive ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 /**
  * 將 Obj 指定的 key 轉換成指定的型別
  *

package/dist/es/useHorizontalWheel-12s-D3IfutV9.mjs

@@ -0,0 +1,47 @@
+'use client';
+import { useRef, useEffect } from 'react';
+
+/**
+ * 將 element 的垂直滾輪事件轉成水平捲動的 hook
+ *
+ * @example
+ *
+ * ```tsx
+ * const ref = useHorizontalWheel();
+ *
+ * return <div ref={ref}>...</div>;
+ *
+ * // 你將可以用垂直滾輪來水平捲動這個 div 了！
+ * ```
+ */ const useHorizontalWheel = ({ speed = 1, respectShiftKey = true } = {})=>{
+    const ref = useRef(null);
+    useEffect(()=>{
+        const el = ref.current;
+        if (!el) return undefined;
+        const onWheel = (e)=>{
+            if (respectShiftKey && e.shiftKey) return;
+            // deltaY 是「想往下滾」的意圖，我們把它轉成 scrollLeft
+            const delta = e.deltaY * speed;
+            const maxScrollLeft = el.scrollWidth - el.clientWidth;
+            const next = el.scrollLeft + delta;
+            const canScrollHorizontally = el.scrollWidth > el.clientWidth;
+            if (!canScrollHorizontally) return;
+            const willScroll = delta < 0 && el.scrollLeft > 0 || delta > 0 && el.scrollLeft < maxScrollLeft;
+            // 只在「容器還能橫向捲」時攔截，避免卡住頁面垂直捲動
+            if (willScroll) {
+                e.preventDefault();
+                el.scrollLeft = Math.max(0, Math.min(maxScrollLeft, next));
+            }
+        };
+        el.addEventListener('wheel', onWheel, {
+            passive: false
+        });
+        return ()=>el.removeEventListener('wheel', onWheel);
+    }, [
+        speed,
+        respectShiftKey
+    ]);
+    return ref;
+};
+
+export { useHorizontalWheel as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [