fui-material 2.8.23 → 2.8.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -28,6 +28,17 @@ export interface ISubmitFiltersOptions<TFilters> {
28
28
  /** Добавочный суффикс к URL (например, /export) */
29
29
  dopUrl?: string;
30
30
  }
31
+ /**
32
+ * Опции для функции `refetch` ручного перезапуска запроса.
33
+ */
34
+ export interface IRefetchPaginationOptions {
35
+ /**
36
+ * Сбрасывать ли номер страницы на 1 при повторном запросе.
37
+ * - Для `mode: 'pagination'` по умолчанию `false` (перезапрашивается текущая страница).
38
+ * - Для `mode: 'infinite'` по умолчанию `true` (сбрасывает на страницу 1 и заменяет накопленные данные).
39
+ */
40
+ resetPage?: boolean;
41
+ }
31
42
  /**
32
43
  * Опции для универсального хука `useFManualPagination`
33
44
  *
@@ -100,6 +111,28 @@ export interface IUseFManualPaginationResult<TData, TFilters = unknown, TQueryFn
100
111
  changePage: (newPage: number) => Promise<TData>;
101
112
  /** Подгрузка следующей страницы (для бесконечного скролла) */
102
113
  loadMore: () => Promise<TData | undefined>;
114
+ /**
115
+ * Повторный запуск запроса с текущими фильтрами и параметрами пагинации.
116
+ * Полный аналог `refetch` из `useQuery` TanStack Query:
117
+ * - Повторно выполняет запрос к серверу без необходимости заново передавать объект фильтров.
118
+ * - Возвращает `Promise<TData>` со свежими извлеченными данными.
119
+ * - Не сбрасывает `isLoading` в `true`, обновляя только флаг фонового запроса `isFetching`.
120
+ *
121
+ * @param options Опции повторного запроса:
122
+ * - `resetPage?: boolean` — сбрасывать ли страницу на 1. По умолчанию `false` для режима `pagination` (сохраняет текущую страницу) и `true` для режима `infinite` (перезагружает ленту с начала).
123
+ *
124
+ * @example
125
+ * // Обновление данных текущей страницы после редактирования записи
126
+ * const handleUpdate = async () => {
127
+ * await updateItem(id, payload);
128
+ * const freshData = await refetch();
129
+ * };
130
+ *
131
+ * @example
132
+ * // Принудительный сброс на 1-ю страницу при перезапросе
133
+ * await refetch({ resetPage: true });
134
+ */
135
+ refetch: (options?: IRefetchPaginationOptions) => Promise<TData>;
103
136
  /** Готовые пропсы для передачи в <FPagination {...paginationProps} /> */
104
137
  paginationProps: IFPagination;
105
138
  }
@@ -1,3 +1,42 @@
1
1
  import { IUseFManualPaginationOptions, IUseFManualPaginationResult } from './types';
2
+ /**
3
+ * Универсальный контроллер серверной пагинации и аналитических отчетов.
4
+ *
5
+ * Хук предназначен для ручного (императивного) запуска запросов с фильтрацией, пагинацией
6
+ * и поддержкой бесконечного скролла (Infinite Scroll).
7
+ *
8
+ * ### Основные возможности:
9
+ * - 🎯 **Ручной запуск (`submitFilters`):** запрос не выполняется автоматически при монтировании компонента.
10
+ * - 🔄 **Авто-склеивание параметров:** сохраняет переданные фильтры при пагинации (`mergeParams: true`).
11
+ * - 🔁 **Повторный запуск (`refetch`):** повтор запроса с текущими фильтрами и страницей (аналог `refetch` из `useQuery`).
12
+ * - 🪄 **Два режима работы (`mode`):**
13
+ * - `'pagination'` (по умолчанию) — заменяет данные при переходе между страницами (`FPagination`).
14
+ * - `'infinite'` — накапливает данные порциями для бесконечного скролла (`FProgressiveList`).
15
+ * - 🛡️ **Защита от мерцания UI:** раздельные индикаторы `isLoading` (первичная загрузка) и `isFetchingMore` (подгрузка скролла).
16
+ * - 🛑 **Отмена устаревших запросов:** автоматическое прерывание предыдущего запроса через `AbortController`.
17
+ *
18
+ * @template TQueryFnData Тип сырого ответа бекенда (например, Spring Data Page или API-ответ)
19
+ * @template TData Тип извлеченных данных после `select` (по умолчанию `TQueryFnData`)
20
+ * @template TFilters Тип параметров фильтрации (body или query params)
21
+ *
22
+ * @param options Конфигурация хука: эндпоинт, ключ кэша, селекторы, режим пагинации и настройки уведомлений
23
+ * @returns Контроллер пагинации: данные, метаданные, состояния загрузки и функции управления (`submitFilters`, `changePage`, `loadMore`, `refetch`, `paginationProps`)
24
+ *
25
+ * @example
26
+ * ```tsx
27
+ * const { data, isLoading, isFetching, submitFilters, refetch, paginationProps } = useFManualPagination({
28
+ * queryKey: 'registry',
29
+ * url: '/api/v1/items',
30
+ * defaultPageSize: 10,
31
+ * select: (res) => res.result,
32
+ * });
33
+ *
34
+ * // Запуск с новыми фильтрами:
35
+ * submitFilters({ payload: { status: 'active' } });
36
+ *
37
+ * // Повторный запрос текущей страницы:
38
+ * await refetch();
39
+ * ```
40
+ */
2
41
  export declare function useFManualPagination<TQueryFnData = unknown, TData = TQueryFnData, TFilters = unknown>(options: IUseFManualPaginationOptions<TQueryFnData, TData, TFilters>): IUseFManualPaginationResult<TData, TFilters, TQueryFnData>;
3
42
  export default useFManualPagination;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fui-material",
3
- "version": "2.8.23",
3
+ "version": "2.8.24",
4
4
  "type": "module",
5
5
  "publishConfig": {
6
6
  "access": "public",