fui-material 2.6.13 → 2.7.0

package/dist/types/context/LibraryProvider.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { AxiosRequestConfig } from 'axios';
+export interface ILibApiService {
+    request: <T>(url: string, config: AxiosRequestConfig) => Promise<T>;
+}
+export interface LibraryConfig {
+    apiService: ILibApiService;
+}
+export declare const LibraryProvider: ({ children, config }: {
+    children: ReactNode;
+    config: LibraryConfig;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const useLibraryContext: () => LibraryConfig;

package/dist/types/hooks/index.d.ts

@@ -1 +1,4 @@
 export { default as useFApi } from "./useFApi";
+export { default as useApiMutation } from "./useApiMutation";
+export { default as useApiQuery } from "./useApiQuery";
+export { default as useManualApiQuery } from "./useManualApiQuery";

package/dist/types/hooks/types.d.ts

@@ -0,0 +1,13 @@
+import { AxiosError } from "axios";
+export interface ExtraOptions {
+    onErrorNotification?: boolean;
+    onErrorLog?: boolean;
+    onLoadingLog?: boolean;
+    onSuccessNotification?: boolean;
+    notificationTitle?: string;
+    notificationBody?: (error: AxiosError | null) => string;
+    loadingNotificationTitle?: string;
+    loadingNotificationBody?: string;
+    successNotificationTitle?: string;
+    successNotificationBody?: string;
+}

package/dist/types/hooks/useApiMutation/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./useApiMutation";

package/dist/types/hooks/useApiMutation/useApiMutation.d.ts

@@ -0,0 +1,75 @@
+import { AxiosError, AxiosRequestConfig } from "axios";
+import { MutateOptions, QueryKey, UseMutationOptions, UseMutationResult } from "@tanstack/react-query";
+import { ExtraOptions } from "../types";
+/**
+ * Возвращаемый тип кастомной мутации с удобной сигнатурой вызова `mutate` и `mutateAsync`
+ */
+export type CustomMutationResult<TData, TError, TVariables, TContext> = Omit<UseMutationResult<TData, TError, {
+    data?: TVariables;
+    urlParams?: Record<string, string | number>;
+}, TContext>, 'mutate' | 'mutateAsync'> & {
+    /**
+     * Функция для запуска мутации.
+     * @param data Данные для отправки (тело POST/PUT запроса или FormData)
+     * @param urlParams Параметры для подстановки в URL (заменяет `:param` на значение)
+     */
+    mutate: (data?: TVariables, urlParams?: Record<string, string | number>, options?: MutateOptions<TData, TError, {
+        data?: TVariables;
+        urlParams?: Record<string, string | number>;
+    }, TContext>) => void;
+    /**
+     * Асинхронная функция для запуска мутации. Возвращает Promise с результатом запроса.
+     * @param data Данные для отправки (тело POST/PUT запроса или FormData)
+     * @param urlParams Параметры для подстановки в URL (заменяет `:param` на значение)
+     */
+    mutateAsync: (data?: TVariables, urlParams?: Record<string, string | number>, options?: MutateOptions<TData, TError, {
+        data?: TVariables;
+        urlParams?: Record<string, string | number>;
+    }, TContext>) => Promise<TData>;
+};
+/**
+ * Хук для выполнения мутаций (POST, PUT, DELETE) с поддержкой динамических параметров в URL и автоматической инвалидацией кэша.
+ *
+ * @template TQueryFnData - Тип ответа от сервера
+ * @template TVariables - Тип отправляемых данных (тело запроса)
+ *
+ * @param url - URL эндпоинта. Поддерживает динамические параметры, например `/api/v1/users/:id/roles`
+ * @param config - Конфигурация Axios
+ * @param options - Расширенные опции useMutation + `queryKeyToInvalidate` для автоматического сброса кэша и опции нотификаций.
+ *
+ * @example
+ * // 1. Простая отправка формы (синхронная):
+ * const { mutate, isPending } = useApiMutation<IUser, ICreateUserDto>(
+ *   '/api/v1/users',
+ *   undefined,
+ *   {
+ *     queryKeyToInvalidate: ['users'],
+ *     onErrorNotification: true
+ *   }
+ * );
+ *
+ * const handleSubmit = (formData: ICreateUserDto) => {
+ *   mutate(formData);
+ * };
+ *
+ * @example
+ * // 2. Запрос с динамическим URL и async/await:
+ * const { mutateAsync } = useApiMutation<void, IRoleDto>('/api/v1/users/:userId/roles/:roleId');
+ *
+ * const handleAssignRole = async () => {
+ *   try {
+ *     await mutateAsync({ permissions: ['read'] }, { userId: 42, roleId: 5 });
+ *     toast.success('Роль успешно назначена!');
+ *   } catch (e) {
+ *     // Обработка ошибки
+ *   }
+ * };
+ */
+export declare const useApiMutation: <TQueryFnData, TVariables = unknown>(url: string, config?: AxiosRequestConfig, options?: Omit<UseMutationOptions<TQueryFnData, AxiosError, {
+    data?: TVariables;
+    urlParams?: Record<string, string | number>;
+}, unknown>, "mutationFn"> & {
+    /** Ключ кэша TanStack Query, который нужно автоматически инвалидировать (обновить) при успехе */
+    queryKeyToInvalidate?: QueryKey;
+} & ExtraOptions) => CustomMutationResult<TQueryFnData, AxiosError, TVariables, unknown>;
+export default useApiMutation;

package/dist/types/hooks/useApiQuery/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./useApiQuery";

package/dist/types/hooks/useApiQuery/useApiQuery.d.ts

@@ -0,0 +1,38 @@
+import { AxiosError, AxiosRequestConfig } from "axios";
+import { QueryKey, UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
+import { ExtraOptions } from "../types";
+/**
+ * Хук для автоматических декларативных запросов (GET/POST).
+ * Параметры запроса автоматически извлекаются из последнего элемента `queryKey`, если это объект.
+ * Запрос запускается автоматически при монтировании и изменении `queryKey`.
+ *
+ * @template TQueryFnData - Тип данных, которые возвращает сервер
+ * @template TData - Тип возвращаемых данных (после возможной трансформации через `select`). По умолчанию = TQueryFnData.
+ *
+ * @param queryKey - Ключ кэширования. Если последний элемент - объект, он передается как `params` (GET) или `data` (POST).
+ * @param url - URL эндпоинта.
+ * @param config - Конфигурация Axios (заголовки, таймауты и т.д., кроме `params`, `data`, `method`).
+ * @param options - Расширенные опции TanStack Query (`enabled`, `staleTime`, `select` и т.д.) + опции нотификаций.
+ *
+ * @returns Стандартный результат `useQuery` (`data`, `isLoading`, `isError`, `refetch` и т.д.).
+ *
+ * @example
+ * // 1. Простой GET-запрос параметров:
+ * const { data, isLoading } = useApiQuery<IUser[]>(
+ *   ['users', { page: 1, limit: 10 }],
+ *   '/api/v1/users'
+ * );
+ *
+ * @example
+ * // 2. POST-запрос справочника с нотификацией об ошибке:
+ * const { data, error } = useApiQuery<IDirectoryResponse>(
+ *   ['dictionary', { category: 'cities' }],
+ *   '/api/v1/dictionary',
+ *   undefined,
+ *   { method: 'POST', onErrorNotification: true }
+ * );
+ */
+declare const useApiQuery: <TQueryFnData, TData = TQueryFnData>(queryKey: QueryKey, url: string, config?: Omit<AxiosRequestConfig, "params" | "data" | "method">, options?: Omit<UseQueryOptions<TQueryFnData, AxiosError, TData>, "queryKey" | "queryFn"> & {
+    method?: "GET" | "POST";
+} & ExtraOptions) => UseQueryResult<TData, AxiosError>;
+export default useApiQuery;

package/dist/types/hooks/useManualApiQuery/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./useManualApiQuery";

package/dist/types/hooks/useManualApiQuery/useManualApiQuery.d.ts

@@ -0,0 +1,65 @@
+import { AxiosError, AxiosRequestConfig } from "axios";
+import { UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
+import { ExtraOptions } from "../types";
+/**
+ * Параметры для функции `run`, запускающей запрос вручную.
+ * @template T - Тип передаваемых параметров запроса (тело POST или GET-параметры)
+ */
+export interface IUseManualApiQueryRun<T> {
+    /** Новые основные параметры запроса (передаются как `data` в POST или `params` в GET) */
+    newParams?: T;
+    /** Дополнительные URL-параметры (query string) */
+    newUrlParams?: Record<string, unknown>;
+    /** Если `true`, сохраняет предыдущие `params`, если `newParams` не был передан */
+    preserveParams?: boolean;
+    /** Добавочный суффикс к URL (например, `/export` или `/:id`) */
+    dopUrl?: string;
+    /** Если `true`, объединяет новые `newUrlParams` со старыми вместо перезаписи */
+    preserveUrlParams?: boolean;
+}
+/**
+ * Тип возвращаемого значения хука `useManualApiQuery` с описанием функции `run` для подсказок IDE
+ */
+export type UseManualApiQueryResult<TData, TVariables> = UseQueryResult<TData, AxiosError> & {
+    /**
+     * Асинхронная функция для ручного запуска HTTP-запроса.
+     * Обновляет параметры, выполняет запрос, сохраняет результат в кэш TanStack Query и возвращает его.
+     *
+     * @param options Параметры запуска (новые params, urlParams, dopUrl и флаги сохранения)
+     * @returns Promise с данными ответа сервера (TData)
+     *
+     * @example
+     * // Вызов с новыми параметрами:
+     * const data = await run({ newParams: { page: 1 } });
+     *
+     * @example
+     * // Повторный вызов с текущими параметрами:
+     * await run();
+     */
+    run: (options?: IUseManualApiQueryRun<TVariables>) => Promise<TData>;
+    /** Текущие основные параметры запроса */
+    params: TVariables | undefined;
+    /** Текущие дополнительные URL-параметры (query string) */
+    urlParams: Record<string, unknown> | undefined;
+};
+/**
+ * Обновленный хук-надстройка над TanStack Query (`useQuery`) для ручного запуска HTTP-запросов с динамическими параметрами.
+ * Подходит для сложных фильтров, экспорта или получения справочников (в т.ч. через POST) с поддержкой кэширования.
+ *
+ * @template TQueryFnData - Тип данных, которые возвращает сервер
+ * @template TData - Тип возвращаемых данных (после возможной трансформации через `select`). По умолчанию = TQueryFnData.
+ * @template TVariables - Тип параметров запроса (body или query params)
+ *
+ * @param queryKey - Базовый ключ кэширования TanStack Query.
+ * @param url - URL эндпоинта.
+ * @param initialParams - Начальные параметры запроса (опционально).
+ * @param config - Конфиг Axios (заголовки, таймауты и т.д., за исключением `data`, `params`, `method`).
+ * @param options - Расширенные опции TanStack Query + дополнительные параметры (`method`, `onErrorNotification` и др.).
+ *
+ * @returns Объект `useQuery` + функция `run` (возвращает `Promise<TData>`) и текущие параметры (`params`, `urlParams`).
+ */
+declare function useManualApiQuery<TQueryFnData, TData = TQueryFnData, TVariables = unknown>(queryKey: string, url: string, initialParams?: TVariables, config?: Omit<AxiosRequestConfig, 'params' | 'data' | 'method'>, options?: Omit<UseQueryOptions<TQueryFnData, AxiosError, TData>, 'queryKey' | 'queryFn'> & {
+    method?: 'GET' | 'POST';
+    urlParams?: Record<string, unknown>;
+} & ExtraOptions): UseManualApiQueryResult<TData, TVariables>;
+export default useManualApiQuery;

package/package.json

@@ -1,81 +1,82 @@
-{
-  "name": "fui-material",
-  "version": "2.6.13",
-  "type": "module",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "author": "Allori",
-  "license": "ISC",
-  "private": false,
-  "scripts": {
-    "dev": "vite",
-    "build:types": "tsc --project tsconfig.build.json",
-    "build": "vite build && npm run build:types",
-    "build-publish": "vite build && npm run build:types && npm publish",
-    "lint": "eslint .",
-    "preview": "vite preview",
-    "storybook": "storybook dev -p 6006",
-    "deploy-storybook": "storybook build && gh-pages -d storybook-static --repo https://github.com/Allorion/fui-storybook.git",
-    "build-storybook": "storybook build"
-  },
-  "dependencies": {
-    "allorion-exporting-html-to-docx": "1.4.1",
-    "allorion-exporting-html-to-xlsx": "1.9.0",
-    "axios": "^1.7.4",
-    "jszip": "^3.10.1"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@chromatic-com/storybook": "^3.2.6",
-    "@eslint/js": "^9.25.0",
-    "@rollup/plugin-image": "^3.0.3",
-    "@storybook/addon-docs": "8.6.12",
-    "@storybook/addon-essentials": "^8.6.12",
-    "@storybook/addon-interactions": "^8.6.12",
-    "@storybook/addon-onboarding": "^8.6.12",
-    "@storybook/addon-styling-webpack": "^1.0.1",
-    "@storybook/blocks": "^8.6.12",
-    "@storybook/react": "^8.6.12",
-    "@storybook/react-vite": "^8.6.12",
-    "@storybook/test": "^8.6.12",
-    "@types/minimatch": "^6.0.0",
-    "@types/node": "^22.4.1",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@vitejs/plugin-react": "^4.4.1",
-    "@vitest/browser": "^3.1.3",
-    "@vitest/coverage-v8": "^3.1.3",
-    "eslint": "^9.25.0",
-    "eslint-plugin-react-hooks": "^5.2.0",
-    "eslint-plugin-react-refresh": "^0.4.19",
-    "eslint-plugin-storybook": "^0.12.0",
-    "gh-pages": "6.3.0",
-    "globals": "^16.0.0",
-    "playwright": "^1.52.0",
-    "rollup-plugin-copy": "^3.5.0",
-    "sass": "1.88.0",
-    "storybook": "^8.6.12",
-    "typescript": "~5.8.3",
-    "typescript-eslint": "^8.30.1",
-    "vite": "^6.3.5",
-    "vite-plugin-lib-inject-css": "^2.1.1",
-    "vitest": "^3.1.3"
-  },
-  "main": "dist/f-ui-kit.umd.js",
-  "module": "dist/f-ui-kit.es.js",
-  "types": "dist/types/index.d.ts",
-  "files": [
-    "dist",
-    "dist/types"
-  ],
-  "eslintConfig": {
-    "extends": [
-      "plugin:storybook/recommended"
-    ]
-  }
+{
+  "name": "fui-material",
+  "version": "2.7.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "Allori",
+  "license": "ISC",
+  "private": false,
+  "scripts": {
+    "dev": "vite",
+    "build:types": "tsc --project tsconfig.build.json",
+    "build": "vite build && npm run build:types",
+    "build-publish": "vite build && npm run build:types && npm publish",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "storybook": "storybook dev -p 6006",
+    "deploy-storybook": "storybook build && gh-pages -d storybook-static --repo https://github.com/Allorion/fui-storybook.git",
+    "build-storybook": "storybook build"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.101.4",
+    "allorion-exporting-html-to-docx": "1.4.1",
+    "allorion-exporting-html-to-xlsx": "1.9.0",
+    "axios": "^1.7.4",
+    "jszip": "^3.10.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^3.2.6",
+    "@eslint/js": "^9.25.0",
+    "@rollup/plugin-image": "^3.0.3",
+    "@storybook/addon-docs": "8.6.12",
+    "@storybook/addon-essentials": "^8.6.12",
+    "@storybook/addon-interactions": "^8.6.12",
+    "@storybook/addon-onboarding": "^8.6.12",
+    "@storybook/addon-styling-webpack": "^1.0.1",
+    "@storybook/blocks": "^8.6.12",
+    "@storybook/react": "^8.6.12",
+    "@storybook/react-vite": "^8.6.12",
+    "@storybook/test": "^8.6.12",
+    "@types/minimatch": "^6.0.0",
+    "@types/node": "^22.4.1",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.4.1",
+    "@vitest/browser": "^3.1.3",
+    "@vitest/coverage-v8": "^3.1.3",
+    "eslint": "^9.25.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.19",
+    "eslint-plugin-storybook": "^0.12.0",
+    "gh-pages": "6.3.0",
+    "globals": "^16.0.0",
+    "playwright": "^1.52.0",
+    "rollup-plugin-copy": "^3.5.0",
+    "sass": "1.88.0",
+    "storybook": "^8.6.12",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.30.1",
+    "vite": "^6.3.5",
+    "vite-plugin-lib-inject-css": "^2.1.1",
+    "vitest": "^3.1.3"
+  },
+  "main": "dist/f-ui-kit.umd.js",
+  "module": "dist/f-ui-kit.es.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "dist/types"
+  ],
+  "eslintConfig": {
+    "extends": [
+      "plugin:storybook/recommended"
+    ]
+  }
 }