@flow97/react-toolkit 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # react-toolkits
 
+## 0.0.4
+
+### Patch Changes
+
+- 2cab4f1: refactor: enhance KyMethods interface to support responseType for blob data
+
+## 0.0.3
+
+### Patch Changes
+
+- df5b54f: refactor: rename ToolkitsProvider to ToolkitProvider and update related imports
+
 ## 0.0.2
 
 ### Patch Changes

package/README.md

@@ -37,7 +37,7 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import 'react-toolkits/style.css'
 import { createRoot } from 'react-dom/client'
 import { RouterProvider } from 'react-router'
-import { ToolkitsProvider } from 'react-toolkits/components'
+import { ToolkitProvider } from 'react-toolkits/components'
 import { AuthMode } from 'react-toolkits/constants'
 
 import router from './router'
@@ -61,16 +61,16 @@ const root = createRoot(document.getElementById('root') as HTMLElement)
 
 root.render(
   <QueryClientProvider client={queryClient}>
-    <ToolkitsProvider collapsible gameApiV2 auth={{ mode: AuthMode.GROUP_BASED }} loginPath="/sign_in" mainPagePath="/">
+    <ToolkitProvider collapsible gameApiV2 auth={{ mode: AuthMode.GROUP_BASED }} loginPath="/sign_in" mainPagePath="/">
       <RouterProvider router={router} />
-    </ToolkitsProvider>
+    </ToolkitProvider>
   </QueryClientProvider>,
 )
 ```
 
-**重要提示**：`QueryClientProvider` 必须包裹 `ToolkitsProvider`，因为 `react-toolkits` 内部使用了 `@tanstack/react-query` 的 hooks（如 `useQueryClient`、`useQuery`、`useMutation`）。
+**重要提示**：`QueryClientProvider` 必须包裹 `ToolkitProvider`，因为 `react-toolkits` 内部使用了 `@tanstack/react-query` 的 hooks（如 `useQueryClient`、`useQuery`、`useMutation`）。
 
-### 配置项（`ToolkitsProvider`）
+### 配置项（`ToolkitProvider`）
 
 - **loginPath**: 登录页路径（未鉴权时会跳转）
 - **mainPagePath**: 登录后主页路径（鉴权通过时进入）
@@ -81,7 +81,7 @@ root.render(
 
 ## 子路径导出（推荐）
 
-- `react-toolkits/components`：组件与 Hooks（如 `Layout`、`ToolkitsProvider`、`InfiniteList`）
+- `react-toolkits/components`：组件与 Hooks（如 `Layout`、`ToolkitProvider`、`InfiniteList`）
 - `react-toolkits/hooks`：表单弹层 Hooks（如 `useFormDrawer`、`useFormModal`）
 - `react-toolkits/pages`：内置页面与路由片段（如 `permissionRoutes`、`menuRoutes`、`SignIn`）
 - `react-toolkits/services`：请求相关 Hooks（如 `useAuth`、`useMenuList`、`useGames`）
@@ -324,13 +324,13 @@ export default function FetchWithKy() {
 过去：
 
 ```ts
-import { ToolkitsProvider, Layout, useFormDrawer } from '@flow97/react-toolkit'
+import { ToolkitProvider, Layout, useFormDrawer } from '@flow97/react-toolkit'
 ```
 
 现在（推荐）：
 
 ```ts
-import { ToolkitsProvider, Layout } from 'react-toolkits/components'
+import { ToolkitProvider, Layout } from 'react-toolkits/components'
 import { useFormDrawer, useFormModal } from 'react-toolkits/hooks'
 import { permissionRoutes } from 'react-toolkits/pages'
 import { useAuth } from 'react-toolkits/services'
@@ -341,14 +341,14 @@ import { useAuth } from 'react-toolkits/services'
 ### 权限版本兼容
 
 - 历史上存在不同权限数据结构，`AuthMode` 用于适配后端变体
-- 新项目建议使用 `V3`；旧项目如为 `V2`，只需在 `ToolkitsProvider` 中切换版本
+- 新项目建议使用 `V3`；旧项目如为 `V2`，只需在 `ToolkitProvider` 中切换版本
 
 ## 常见问题（FAQ）
 
 - 如何引入样式？
   - 在应用入口一次性引入：`import 'react-toolkits/style.css'`
 - Provider 放哪？
-  - 在应用根部使用 `ToolkitsProvider`，传入登录路径、主页路径、权限版本等配置。
+  - 在应用根部使用 `ToolkitProvider`，传入登录路径、主页路径、权限版本等配置。
 - 如何自定义菜单？
   - 通过 `Layout` 的 `items` 或参考示例应用的 `menu-items.tsx`。
 - 如何统一请求与拦截？

package/lib/index.d.ts

@@ -8,14 +8,14 @@ import { ItemType, SubMenuType, MenuItemGroupType, MenuItemType } from 'antd/es/
 import { AnyObject } from 'antd/es/_util/type';
 import { TableProps } from 'antd/es/table';
 import * as zustand from 'zustand';
-import { StateCreator } from 'zustand';
+import { StoreApi, StateCreator } from 'zustand';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { StateStorage } from 'zustand/middleware';
 
 /** 响应类型 */
 type ResponseType = 'json' | 'blob' | 'text' | 'arrayBuffer' | 'formData';
 /** 通用请求选项接口 */
-interface RequestOptions extends Options {
+interface RequestOptions extends Omit<Options, 'hooks'> {
     /** 响应类型 */
     responseType?: ResponseType;
     /** 是否使用全局模式，为 true 时 app-id header 设置为 global */
@@ -620,7 +620,7 @@ interface QueryListRequestConfig extends CacheConfig {
     body?: FormData | Record<string | number, any>;
     searchParams?: Record<string | number, any>;
     headers?: Record<string, string>;
-    /** 是否使用全局模式（覆盖 ToolkitsProvider 中的 isGlobalMode） */
+    /** 是否使用全局模式（覆盖 ToolkitProvider 中的 isGlobalMode） */
     isGlobalMode?: boolean;
 }
 /**
@@ -900,6 +900,16 @@ type Locale = {
     };
 };
 
+/**
+ * JWT Token 解密后的用户信息
+ */
+interface UserInfo {
+    authorityId: string;
+    exp: number;
+}
+/**
+ * Context 配置接口
+ */
 interface ContextSlice {
     /** 是否使用游戏 API V2 版本 */
     useGameApiV2: boolean;
@@ -920,17 +930,30 @@ interface ContextSlice {
     /** 认证模式 */
     authMode: AuthMode;
 }
-
+/**
+ * Token 状态接口
+ */
+interface TokenSlice {
+    /** JWT Token */
+    token?: string;
+    user: UserInfo | null;
+    setToken: (token: string) => void;
+    clearToken: () => void;
+}
+/**
+ * Game 状态接口
+ */
 interface GameSlice {
     appId?: string | number;
     setAppId: (id?: string | number) => void;
 }
-
+/**
+ * Layout 状态接口
+ */
 interface LayoutSlice {
     collapsed: boolean;
     toggleCollapsed: () => void;
 }
-
 /**
  * 导航菜单状态接口
  */
@@ -944,23 +967,7 @@ interface NavSlice {
     /** 设置选中的菜单项 */
     setSelectedKeys: (keys: string[]) => void;
 }
-
-/**
- * JWT Token 解密后的用户信息
- */
-interface UserInfo {
-    authorityId: string;
-    exp: number;
-}
-interface TokenSlice {
-    /** JWT Token */
-    token?: string;
-    user: UserInfo | null;
-    setToken: (token: string) => void;
-    clearToken: () => void;
-}
-
-type ToolkitsState = {
+type ToolkitState = {
     context: ContextSlice;
     token: TokenSlice;
     game: GameSlice;
@@ -968,24 +975,22 @@ type ToolkitsState = {
     nav: NavSlice;
     clear: () => void;
 };
+declare const toolkitStore: StoreApi<ToolkitState>;
 
-declare function useToolkitsStore(): ToolkitsState;
-declare function useToolkitsStore<T>(selector: (state: ToolkitsState) => T): T;
-type ToolkitsProviderProps = PropsWithChildren<DeepPartial<ContextSlice>>;
+declare function useToolkitStore(): ToolkitState;
+declare function useToolkitStore<T>(selector: (state: ToolkitState) => T): T;
+type ToolkitProviderProps = PropsWithChildren<DeepPartial<ContextSlice>>;
 /**
- * ToolkitsProvider 组件
+ * ToolkitProvider 组件（全局单例模式，不支持嵌套）
  *
- * 支持嵌套使用，子 Provider 会从最近的父 Provider 继承 context 配置。
- * 子 Provider 的 props 会覆盖父 Provider 的对应配置。
+ * - 使用全局单例的 ToolkitStore（store 在模块加载时已创建）
+ * - 最外层 Provider 的 props 会更新全局 store 的 context 配置
+ * - 内层嵌套的 Provider 将直接抛错，提示不支持嵌套使用
  *
- * 当父级 context 或当前 props 发生变化时，会重新创建 store 以确保配置同步。
- *
- * @example
- * 外层 Provider 和内层 Provider 嵌套使用示例：
- * - 外层：loginPath="/login" apiBaseUrl="https://api.example.com"
- * - 内层：apiBaseUrl="https://api-v2.example.com" (会覆盖外层的 apiBaseUrl)
+ * 使用约定：
+ * - 只在应用根部使用一次 ToolkitProvider
  */
-declare const ToolkitsProvider: FC<ToolkitsProviderProps>;
+declare const ToolkitProvider: FC<ToolkitProviderProps>;
 
 declare const UserDropdown: FC;
 
@@ -1445,4 +1450,4 @@ declare function useAuth(code?: string | string[], config?: RequestOptions): {
 declare function useMenuList(): _tanstack_react_query.UseQueryResult<MenuListItem[], Error>;
 declare const useGames: () => _tanstack_react_query.UseQueryResult<Game[], Error>;
 
-export { APP_ID_HEADER, AuthButton, type AuthButtonProps, AuthMode, DynamicTags, type DynamicTagsProps, ExpandableParagraph, type ExpandableParagraphProps, FRONTEND_ROUTE_PREFIX, FilterFormWrapper, type FilterFormWrapperProps, type Game, type GameSelectConfig, type GameSelectProps, type HeaderExtra, type HeaderExtraConfig, Highlight, type HighlightProps, InfiniteList, type InfiniteListDataAdapter, type InfiniteListPayload, type InfiniteListProps, type InfiniteListRef, type InfiniteListRequestConfig, type InfiniteListRequestConfigType, type JsonResponse, KeepAlive, type KeepAliveCacheItem, KeepAliveOutlet, type KeepAliveOutletProps, type KeepAliveProps, KeepAliveProvider, type KeepAliveProviderProps, Layout, type LayoutProps, Logo, type LogoProps, type MenuListItem, type NavItem, type NavMenuItemGroupType, type NavMenuItemType, type NavSubMenuType, type NavigationConfig, NotFound, OperationLogList, type PageParam, type Permission, QueryList, QueryListAction, type QueryListPayload, type QueryListProps, type QueryListRef, type RecursivePartial, RequireAuth, type RequireAuthProps, RequireGame, type RouteMatchRule, SSO_URL, SelectAll, type SelectAllProps, type ShowFormOptions$1 as ShowFormDrawerOptions, type ShowFormOptions as ShowFormModalOptions, SignIn, ToolkitsProvider, type ToolkitsProviderProps, type UseDrawerOperation, type UseDrawerProps, type UseFormDrawerProps, type UseFormDrawerReturn, type UseFormModalProps, type UseFormModalReturn, type UseKeepAliveReturn, type UseModalOperation, type UseModalProps, UserDropdown, type VisibilityState, WILDCARD, createVisibilityStoreConfig, generateId, _default$1 as menuRoutes, mixedStorage, _default as permissionRoutes, useAuth, useDrawer, useDrawerStore, useFormDrawer, useFormModal, useGames, useInfiniteListStore, useKeepAlive, useKeepAliveContext, useMenuList, useModal, useModalStore, useQueryListStore, useToolkitsStore };
+export { APP_ID_HEADER, AuthButton, type AuthButtonProps, AuthMode, DynamicTags, type DynamicTagsProps, ExpandableParagraph, type ExpandableParagraphProps, FRONTEND_ROUTE_PREFIX, FilterFormWrapper, type FilterFormWrapperProps, type Game, type GameSelectConfig, type GameSelectProps, type HeaderExtra, type HeaderExtraConfig, Highlight, type HighlightProps, InfiniteList, type InfiniteListDataAdapter, type InfiniteListPayload, type InfiniteListProps, type InfiniteListRef, type InfiniteListRequestConfig, type InfiniteListRequestConfigType, type JsonResponse, KeepAlive, type KeepAliveCacheItem, KeepAliveOutlet, type KeepAliveOutletProps, type KeepAliveProps, KeepAliveProvider, type KeepAliveProviderProps, Layout, type LayoutProps, Logo, type LogoProps, type MenuListItem, type NavItem, type NavMenuItemGroupType, type NavMenuItemType, type NavSubMenuType, type NavigationConfig, NotFound, OperationLogList, type PageParam, type Permission, QueryList, QueryListAction, type QueryListPayload, type QueryListProps, type QueryListRef, type RecursivePartial, RequireAuth, type RequireAuthProps, RequireGame, type RouteMatchRule, SSO_URL, SelectAll, type SelectAllProps, type ShowFormOptions$1 as ShowFormDrawerOptions, type ShowFormOptions as ShowFormModalOptions, SignIn, ToolkitProvider, type ToolkitProviderProps, type UseDrawerOperation, type UseDrawerProps, type UseFormDrawerProps, type UseFormDrawerReturn, type UseFormModalProps, type UseFormModalReturn, type UseKeepAliveReturn, type UseModalOperation, type UseModalProps, UserDropdown, type VisibilityState, WILDCARD, createVisibilityStoreConfig, generateId, _default$1 as menuRoutes, mixedStorage, _default as permissionRoutes, toolkitStore, useAuth, useDrawer, useDrawerStore, useFormDrawer, useFormModal, useGames, useInfiniteListStore, useKeepAlive, useKeepAliveContext, useMenuList, useModal, useModalStore, useQueryListStore, useToolkitStore };