@nokecy/qc-ui-components 0.0.0-stage → 2.0.0-beta.0

package/dist/esm/ag-grid-plus/context/useSchemeManager.d.ts

@@ -0,0 +1,117 @@
+import type { GridPlusContextValue } from './gridContext';
+import type { SchemeStorageAdapter, CurrentSchemeDto, ColumnScheme, QueryScheme } from '../shared/storage/schemeStorageAdapter';
+/**
+ * useSchemeManager Hook 配置
+ */
+export interface UseSchemeManagerConfig {
+    /** 存储适配器 */
+    adapter: SchemeStorageAdapter;
+    /** 是否在 mount 时自动加载数据,默认 true */
+    autoLoad?: boolean;
+    /** 加载失败时是否显示错误提示,默认 true */
+    showErrorMessage?: boolean;
+    /** 当前用户ID，用于监听用户切换 */
+    currentUserId?: string | null;
+}
+/**
+ * 集中式方案管理 Hook
+ *
+ * 用于 GridPlusContext.Provider 中初始化方案管理功能
+ *
+ * @example
+ * ```tsx
+ * function AppProvider({ children }) {
+ *   const adapter = new BackendApiSchemeAdapter({ ... });
+ *   const schemeManager = useSchemeManager({ adapter });
+ *
+ *   return (
+ *     <GridPlusContext.Provider value={{
+ *       ...otherValues,
+ *       ...schemeManager
+ *     }}>
+ *       {children}
+ *     </GridPlusContext.Provider>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSchemeManager(config: UseSchemeManagerConfig): {
+    columnSchemes: Record<string, ColumnScheme[]>;
+    querySchemes: Record<string, QueryScheme[]>;
+    currentSchemes: Record<string, CurrentSchemeDto>;
+    schemesLoading: boolean;
+    lastSyncTime: number;
+    saveColumnScheme: (gridId: string, scheme: ColumnScheme) => Promise<void>;
+    deleteColumnScheme: (gridId: string, schemeId: string) => Promise<void>;
+    setCurrentColumnScheme: (gridId: string, schemeId: string | null) => Promise<void>;
+    saveQueryScheme: (gridId: string, scheme: QueryScheme) => Promise<void>;
+    deleteQueryScheme: (gridId: string, schemeId: string) => Promise<void>;
+    setCurrentQueryScheme: (gridId: string, schemeId: string | null) => Promise<void>;
+    refreshSchemes: () => Promise<void>;
+    getColumnSchemes: (gridId: string) => ColumnScheme[];
+    getQuerySchemes: (gridId: string) => QueryScheme[];
+    getCurrentScheme: (gridId: string) => CurrentSchemeDto | null;
+    applySchemeToGlobal: (gridId: string, schemeId?: string) => Promise<string>;
+    resetToGlobal: (gridId: string) => Promise<void>;
+    resetAllUsers: (gridId: string) => Promise<void>;
+};
+/**
+ * 在组件中使用集中式方案管理
+ *
+ * ⚠️ 必须在 Provider 中传入 SchemeManager 状态，否则抛出错误
+ *
+ * @example
+ * ```tsx
+ * // 1. 创建适配器和方案管理器
+ * function App() {
+ *   const adapter = useMemo(
+ *     () => new BackendApiSchemeAdapter({
+ *       apiBaseUrl: 'https://api.example.com',
+ *       getToken: () => localStorage.getItem('token'),
+ *       getUserId: () => localStorage.getItem('userId')
+ *     }),
+ *     []
+ *   );
+ *
+ *   const schemeManager = useSchemeManager({
+ *     adapter,
+ *     autoLoad: true,
+ *     showErrorMessage: true,
+ *     currentUserId: currentUser?.id
+ *   });
+ *
+ *   // 2. 传入 Provider
+ *   return (
+ *     <GridPlusContext.Provider value={{
+ *       extensibleColumns: [],
+ *       columnState: undefined,
+ *       onSaveColumnState: () => {},
+ *       applyToGlobal: () => {},
+ *       resetCurrent: () => {},
+ *       resetAll: () => {},
+ *       queryFormItems: [],
+ *       ...schemeManager  // 展开方案管理状态
+ *     }}>
+ *       <MyGrid />
+ *     </GridPlusContext.Provider>
+ *   );
+ * }
+ *
+ * // 3. 在子组件中使用
+ * function MyGrid() {
+ *   const {
+ *     columnSchemes,
+ *     saveColumnScheme,
+ *     setCurrentColumnScheme
+ *   } = useGridSchemes();
+ *
+ *   const gridId = 'my-grid';
+ *   const schemes = columnSchemes?.[gridId] || [];
+ *
+ *   const handleSave = async () => {
+ *     await saveColumnScheme?.(gridId, newScheme);
+ *   };
+ * }
+ * ```
+ */
+export declare function useGridSchemes(): GridPlusContextValue;