@reformer/ui-kit 7.0.0-beta.1 → 7.0.0-beta.2

package/dist/components/ui/select-resource.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Чистая (React-free) логика асинхронного источника опций для {@link Select}.
+ *
+ * Вынесена из компонента, чтобы стратегии загрузки, слияние страниц и
+ * клиентская фильтрация были юнит-тестируемы без DOM (в монорепо тесты —
+ * логические `.test.ts`, без jsdom/testing-library).
+ *
+ * @module ui/select-resource
+ */
+/** Параметры запроса к {@link ResourceConfig.load}. */
+export interface ResourceLoadParams {
+    /** Поисковый запрос (серверная фильтрация в стратегии `partial`). */
+    search?: string;
+    /** Номер страницы (1-based) для пагинации. */
+    page?: number;
+    /** Размер страницы. */
+    pageSize?: number;
+    /** Дополнительные пользовательские параметры. */
+    [key: string]: unknown;
+}
+/** Один элемент, возвращаемый {@link ResourceConfig.load}. */
+export interface ResourceItem<T> {
+    /** Уникальный ключ элемента (для React `key` и дедупликации страниц). */
+    id: string | number;
+    /** Видимая подпись опции. */
+    label: string;
+    /** Значение, которое попадает в `onChange` (всегда приводится к строке). */
+    value: T;
+    /** Опциональное имя группы — варианты с одинаковым `group` объединяются в `SelectGroup`. */
+    group?: string;
+    /** Дополнительные поля бек-данных. */
+    [key: string]: unknown;
+}
+/** Ответ {@link ResourceConfig.load}. */
+export interface ResourceResult<T> {
+    /** Список вариантов текущей страницы. */
+    items: ResourceItem<T>[];
+    /** Общее число доступных вариантов (для пагинации). */
+    totalCount: number;
+}
+/**
+ * Стратегия загрузки опций {@link Select}:
+ * - `'static'` — один `load({})` при монтировании; без поиска и пагинации (снимок);
+ * - `'preload'` — один `load({})` (сервер возвращает всё), поиск фильтрует
+ *   загруженные опции на клиенте; пагинации нет;
+ * - `'partial'` — серверные поиск и пагинация: `load({ search, page })`,
+ *   догрузка следующих страниц при скролле до `totalCount`.
+ */
+export type ResourceStrategy = 'static' | 'preload' | 'partial';
+/** Конфигурация асинхронного источника опций для {@link Select}. */
+export interface ResourceConfig<T> {
+    /** Стратегия загрузки. По умолчанию (если не задана) трактуется как `'static'`. */
+    type: ResourceStrategy;
+    /** Функция загрузки опций. Должна вернуть `{ items, totalCount }`. */
+    load: (params?: ResourceLoadParams) => Promise<ResourceResult<T>>;
+    /** Размер страницы для стратегии `partial`. По умолчанию 20. */
+    pageSize?: number;
+}
+/** Нормализованная опция: `value` приведён к строке для Radix и `onChange`. */
+export interface NormalizedOption {
+    id: string | number;
+    label: string;
+    value: string;
+    group?: string;
+}
+/** Поведенческие флаги стратегии. */
+export interface StrategyFlags {
+    /** Поиск уходит на сервер (`load({ search })`) vs фильтруется на клиенте. */
+    serverSearch: boolean;
+    /** Опции подгружаются постранично по мере скролла. */
+    paginated: boolean;
+    /** Показывать ли поле поиска в дропдауне. */
+    searchable: boolean;
+}
+/**
+ * Разложить {@link ResourceStrategy} в поведенческие флаги.
+ *
+ * @param type - стратегия (undefined трактуется как `'static'`)
+ * @returns флаги {@link StrategyFlags}
+ */
+export declare function resolveStrategyFlags(type: ResourceStrategy | undefined): StrategyFlags;
+/**
+ * Привести «сырые» элементы ответа к {@link NormalizedOption} (`value` → строка).
+ *
+ * @param items - элементы из {@link ResourceResult.items}
+ * @returns нормализованные опции
+ */
+export declare function normalizeItems<T>(items: ResourceItem<T>[]): NormalizedOption[];
+/**
+ * Слить ранее загруженные опции со страницей новых, отбрасывая дубли по `id`
+ * (сервер может вернуть пересечение при гонке страниц).
+ *
+ * @param prev - уже загруженные опции
+ * @param next - опции новой страницы
+ * @returns объединённый список без повторов `id`
+ */
+export declare function mergeOptions(prev: NormalizedOption[], next: NormalizedOption[]): NormalizedOption[];
+/**
+ * Клиентская фильтрация опций по подстроке `label` (case-insensitive).
+ * Используется стратегией `preload`; пустой запрос возвращает исходный список.
+ *
+ * @param options - загруженные опции
+ * @param query - строка поиска
+ * @returns отфильтрованные опции
+ */
+export declare function filterClient(options: NormalizedOption[], query: string): NormalizedOption[];
+/** Состояние загрузки асинхронного источника. */
+export interface ResourceState {
+    /** Накопленные (по страницам) опции — уже нормализованные. */
+    options: NormalizedOption[];
+    /** Последняя загруженная страница (1-based). */
+    page: number;
+    /** Общее число опций по данным сервера. */
+    totalCount: number;
+    /** Первичная загрузка (маунт или смена запроса). */
+    loading: boolean;
+    /** Догрузка следующей страницы. */
+    loadingMore: boolean;
+    /** Последняя загрузка завершилась ошибкой. */
+    error: boolean;
+    /** Активный (применённый) поисковый запрос. */
+    search: string;
+}
+export type ResourceAction<T> = {
+    kind: 'load-start';
+    search: string;
+} | {
+    kind: 'load-success';
+    result: ResourceResult<T>;
+    page: number;
+} | {
+    kind: 'load-more-start';
+} | {
+    kind: 'load-more-success';
+    result: ResourceResult<T>;
+    page: number;
+} | {
+    kind: 'load-error';
+    more?: boolean;
+} | {
+    kind: 'reset';
+};
+/** Начальное состояние источника. */
+export declare function initialResourceState(): ResourceState;
+/**
+ * Чистый reducer состояния асинхронного источника опций.
+ *
+ * - `load-start` сбрасывает список (новый запрос/маунт) и поднимает `loading`;
+ * - `load-success` заменяет опции первой страницей;
+ * - `load-more-*` аппендит следующую страницу (с дедупликацией по `id`);
+ * - `load-error` гасит флаги загрузки и ставит `error`.
+ *
+ * @param state - текущее состояние
+ * @param action - действие {@link ResourceAction}
+ * @returns новое состояние
+ */
+export declare function resourceReducer<T>(state: ResourceState, action: ResourceAction<T>): ResourceState;
+/**
+ * Есть ли ещё непогруженные страницы (для infinite-scroll в стратегии `partial`).
+ *
+ * @param state - состояние источника
+ * @returns `true`, если загружено меньше опций, чем `totalCount`
+ */
+export declare function hasMore(state: ResourceState): boolean;
+/**
+ * Достигнут ли порог подгрузки при прокрутке контейнера опций.
+ *
+ * @param el - метрики скролла контейнера
+ * @param threshold - запас в пикселях до низа (по умолчанию 48)
+ * @returns `true`, если пора грузить следующую страницу
+ */
+export declare function isNearBottom(el: {
+    scrollTop: number;
+    clientHeight: number;
+    scrollHeight: number;
+}, threshold?: number): boolean;

package/dist/components/ui/select-resource.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/ui/select.d.ts

@@ -1,48 +1,7 @@
+import { ResourceConfig } from './select-resource';
 import * as React from 'react';
 import * as SelectPrimitive from '@radix-ui/react-select';
-/** Параметры запроса к {@link ResourceConfig.load}. */
-interface ResourceLoadParams {
-    /** Поисковый запрос (для async-фильтрации). */
-    search?: string;
-    /** Номер страницы (1-based) для пагинации. */
-    page?: number;
-    /** Размер страницы. */
-    pageSize?: number;
-    /** Дополнительные пользовательские параметры. */
-    [key: string]: unknown;
-}
-/** Один элемент, возвращаемый {@link ResourceConfig.load}. */
-interface ResourceItem<T> {
-    /** Уникальный ключ элемента (для React `key`). */
-    id: string | number;
-    /** Видимая подпись опции. */
-    label: string;
-    /** Значение, которое попадает в `onChange` (всегда приводится к строке). */
-    value: T;
-    /** Опциональное имя группы — варианты с одинаковым `group` объединяются в `SelectGroup`. */
-    group?: string;
-    /** Дополнительные поля бек-данных. */
-    [key: string]: unknown;
-}
-/** Ответ {@link ResourceConfig.load}. */
-interface ResourceResult<T> {
-    /** Список вариантов. */
-    items: ResourceItem<T>[];
-    /** Общее число доступных вариантов (для пагинации). */
-    totalCount: number;
-}
-/** Конфигурация асинхронного источника опций для {@link Select}. */
-export interface ResourceConfig<T> {
-    /**
-     * Стратегия загрузки:
-     * - `'static'` — варианты загружаются один раз и больше не меняются;
-     * - `'preload'` — загрузка на маунт компонента (используется по умолчанию в {@link Select});
-     * - `'partial'` — порционная загрузка (нужен будет внешний механизм пагинации).
-     */
-    type: 'static' | 'preload' | 'partial';
-    /** Функция загрузки опций. Должна вернуть `{ items, totalCount }`. */
-    load: (params?: ResourceLoadParams) => Promise<ResourceResult<T>>;
-}
+export type { ResourceConfig, ResourceLoadParams, ResourceItem, ResourceResult, ResourceStrategy, NormalizedOption, } from './select-resource';
 /** Props компонента {@link Select}. */
 export interface SelectProps<T> extends Omit<React.ComponentProps<typeof SelectPrimitive.Root>, 'value' | 'onValueChange'> {
     /** Дополнительный CSS-класс для триггера. */
@@ -72,9 +31,17 @@ export interface SelectProps<T> extends Omit<React.ComponentProps<typeof SelectP
     clearable?: boolean;
 }
 /**
- * Выпадающий список на `@radix-ui/react-select`. Поддерживает два режима
- * источника данных: inline `options` и async `resource`. При `clearable=true`
- * показывает крестик для сброса значения в `null`.
+ * Выпадающий список на `@radix-ui/react-select`. Два источника данных: inline
+ * `options` и асинхронный `resource` со стратегией загрузки
+ * ({@link ResourceConfig.type}):
+ *
+ * - `static` — один `load({})` при маунте, без поиска;
+ * - `preload` — грузит всё сразу, поиск фильтрует опции на клиенте;
+ * - `partial` — серверные поиск (`load({ search })` с debounce) и пагинация
+ *   (`load({ page })` по мере скролла до `totalCount`).
+ *
+ * Для `preload`/`partial` в дропдауне показывается поле поиска. При
+ * `clearable=true` рядом со значением есть крестик сброса в `null`.
  *
  * @example Inline-options
  * ```tsx
@@ -87,24 +54,47 @@ export interface SelectProps<T> extends Omit<React.ComponentProps<typeof SelectP
  *   options={[
  *     { value: 'consumer', label: 'Потребительский' },
  *     { value: 'mortgage', label: 'Ипотека' },
- *     { value: 'auto', label: 'Авто' },
  *   ]}
  * />
  * ```
  *
- * @example Grouped options
+ * @example Серверные поиск и пагинация (resource type='partial')
  * ```tsx
- * import { Select } from '@reformer/ui-kit';
+ * import { Select, type ResourceConfig } from '@reformer/ui-kit';
+ *
+ * const users: ResourceConfig<string> = {
+ *   type: 'partial',
+ *   pageSize: 20,
+ *   load: async ({ search = '', page = 1, pageSize = 20 }) => {
+ *     const res = await fetch(`/api/users?q=${search}&page=${page}&size=${pageSize}`);
+ *     const { rows, total } = await res.json();
+ *     return {
+ *       items: rows.map((u) => ({ id: u.id, label: u.name, value: u.id })),
+ *       totalCount: total,
+ *     };
+ *   },
+ * };
+ *
+ * <Select value={userId} onChange={setUserId} resource={users} clearable />
+ * ```
  *
- * <Select
- *   value={city}
- *   onChange={setCity}
- *   options={[
- *     { value: 'msk', label: 'Москва', group: 'Россия' },
- *     { value: 'spb', label: 'Санкт-Петербург', group: 'Россия' },
- *     { value: 'minsk', label: 'Минск', group: 'Беларусь' },
- *   ]}
- * />
+ * @example Предзагрузка с клиентским поиском (resource type='preload')
+ * ```tsx
+ * import { Select, type ResourceConfig } from '@reformer/ui-kit';
+ *
+ * const countries: ResourceConfig<string> = {
+ *   type: 'preload',
+ *   load: async () => {
+ *     const res = await fetch('/api/countries');
+ *     const items = await res.json();
+ *     return {
+ *       items: items.map((c) => ({ id: c.id, label: c.name, value: c.code })),
+ *       totalCount: items.length,
+ *     };
+ *   },
+ * };
+ *
+ * <Select value={country} onChange={setCountry} resource={countries} />
  * ```
  */
 declare const Select: React.ForwardRefExoticComponent<SelectProps<any> & {
@@ -199,10 +189,14 @@ declare function SelectTrigger({ className, size, children, 'aria-label': ariaLa
     size?: 'sm' | 'default';
 }): import("react/jsx-runtime").JSX.Element;
 /**
- * Дропдаун-контент {@link Select} (попап со списком). Обёртка над
+ * Дропдаун-контent {@link Select} (попап со списком). Обёртка над
  * `Radix.Select.Content` с порталом, скролл-кнопками сверху/снизу и
  * `position='popper'` по умолчанию (растягивается под ширину триггера).
  *
+ * Опционально принимает `header` (нескроллящаяся шапка, например поле поиска)
+ * и `onViewportScroll` (для infinite-scroll — вешается на скроллящийся
+ * viewport со списком опций).
+ *
  * @example Popper-режим (default — ширина равна триггеру)
  * ```tsx
  * import { SelectContent, SelectItem } from '@reformer/ui-kit/select';
@@ -222,7 +216,12 @@ declare function SelectTrigger({ className, size, children, 'aria-label': ariaLa
  * </SelectContent>
  * ```
  */
-declare function SelectContent({ className, children, position, ...props }: React.ComponentProps<typeof SelectPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+declare function SelectContent({ className, children, position, header, onViewportScroll, ...props }: React.ComponentProps<typeof SelectPrimitive.Content> & {
+    /** Нескроллящаяся шапка над списком (например, поле поиска). */
+    header?: React.ReactNode;
+    /** Обработчик прокрутки viewport-а со списком (для infinite-scroll). */
+    onViewportScroll?: React.UIEventHandler<HTMLDivElement>;
+}): import("react/jsx-runtime").JSX.Element;
 /**
  * Заголовок секции внутри {@link SelectGroup}. Обёртка над
  * `Radix.Select.Label`. Не выбирается; используется для визуального разделения

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export type { RadioGroupProps, RadioOption } from './components/ui/radio-group';
 export { Section } from './components/ui/section';
 export type { SectionProps } from './components/ui/section';
 export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectTrigger, SelectValue, } from './components/ui/select';
-export type { SelectProps } from './components/ui/select';
+export type { SelectProps, ResourceConfig } from './components/ui/select';
 export { Textarea } from './components/ui/textarea';
 export type { TextareaProps } from './components/ui/textarea';
 export { ErrorState } from './components/state/error-state';