barneo-search-widget-lib/src/modules/sharedState/types/index.ts

Библиотека для поиска по каталогу Barneo на Vue 3

/**
 * Типы и интерфейсы общего состояния
 *
 * Этот модуль определяет основные структуры данных и интерфейсы для управления
 * общим состоянием между всеми компонентами Barneo Search Library.
 *
 * @module sharedState
 *
 */

import type { FullProduct } from "../../searchWidget/types/responses";

/**
 * Полное состояние поиска, которое является общим для всех виджетов.
 * Этот интерфейс определяет центральную структуру данных для поисковых операций,
 * фильтров, пагинации и синхронизации компонентов.
 */
export interface SearchState {
  /**
   * Текущая строка поискового запроса.
   * @defaultValue ""
   */
  query: string;

  /**
   * Результаты поиска из API.
   * @defaultValue []
   */
  results: FullProduct[];

  /**
   * Общее количество доступных результатов поиска.
   * @defaultValue 0
   */
  totalResults: number;

  /**
   * Полные данные товаров для виджета товаров.
   * @defaultValue []
   */
  full_products: FullProduct[];

  /**
   * Общее количество доступных товаров.
   * @defaultValue 0
   */
  totalProducts: number;

  /**
   * Доступные фильтры из ответа API.
   * @defaultValue []
   */
  filters: any[]; // Доступные фильтры из API

  /**
   * Текущие активные фильтры.
   * @defaultValue []
   */
  activeFilters: FilterState[];

  /**
   * Продуктовые фильтры для API (checkbox и range фильтры).
   * @defaultValue []
   */
  products: ProductFilter[];

  /**
   * Текущие активные продуктовые фильтры.
   * @defaultValue []
   */
  activeProducts: ProductFilter[];

  /**
   * Текущая опция сортировки.
   * @defaultValue "relevance"
   */
  sort: string;

  /**
   * Состояние пагинации для всех типов данных.
   */
  pagination: {
    /**
     * Количество товаров на странице.
     * @defaultValue 20
     */
    limit_products: number;
    /**
     * Количество категорий на странице.
     * @defaultValue 10
     */
    limit_categories: number;
    /**
     * Количество брендов на странице.
     * @defaultValue 10
     */
    limit_brands: number;
    /**
     * Текущее смещение для товаров.
     * @defaultValue 0
     */
    offset_products: number;
  };

  /**
   * Выполняется ли поисковая операция в данный момент.
   * @defaultValue false
   */
  isLoading: boolean;

  /**
   * Сообщение об ошибке, если поиск не удался.
   * @defaultValue null
   */
  error: string | null;

  /**
   * Временная метка последней поисковой операции.
   * @defaultValue 0
   */
  searchTimestamp: number;

  /**
   * Является ли текущий поиск глубоким поиском.
   * @defaultValue false
   */
  isDeepSearch: boolean;
}

/**
 * Структура состояния отдельного фильтра.
 * Представляет отдельный фильтр с его значениями и состоянием выбора.
 */
export interface FilterState {
  /**
   * Уникальный идентификатор фильтра.
   * @required
   */
  id: string;

  /**
   * Отображаемое имя фильтра.
   * @required
   */
  name: string;

  /**
   * Код/идентификатор фильтра для API запросов.
   * @required
   */
  code: string;

  /**
   * Доступные значения для этого фильтра.
   * @defaultValue []
   */
  values: FilterValue[];
}

/**
 * Структура отдельного значения фильтра.
 * Представляет отдельное значение в рамках фильтра.
 */
export interface FilterValue {
  /**
   * Уникальный идентификатор значения фильтра.
   * @required
   */
  id: string;

  /**
   * Отображаемое имя значения фильтра.
   * @required
   */
  name: string;

  /**
   * Выбрано ли это значение фильтра в данный момент.
   * @defaultValue false
   */
  isSelected: boolean;
}

/**
 * Продуктовый фильтр для API (checkbox и range фильтры).
 * Используется для передачи фильтров в поле products API запроса.
 */
export interface ProductFilter {
  /**
   * Код фильтра.
   * @required
   */
  code: string;

  /**
   * ID значений для checkbox фильтра.
   */
  value_ids?: string[];

  /**
   * Минимальное значение для range фильтра.
   */
  value_gte?: string;

  /**
   * Максимальное значение для range фильтра.
   */
  value_lte?: string;
}

/**
 * Интерфейс событий для межвиджетного взаимодействия.
 * Определяет функции обратного вызова для различных изменений состояния.
 */
export interface SharedStateEvents {
  /**
   * Вызывается при получении результатов поиска.
   * @param {SearchState} state - Полное состояние поиска
   */
  onSearchResults: (state: SearchState) => void;

  /**
   * Вызывается при возникновении ошибки поиска.
   * @param {string} error - Сообщение об ошибке
   */
  onSearchError: (error: string) => void;

  /**
   * Вызывается при изменении состояния загрузки поиска.
   * @param {boolean} loading - Состояние загрузки
   */
  onSearchLoading: (loading: boolean) => void;

  /**
   * Вызывается при изменении фильтров.
   * @param {FilterState[]} filters - Обновленные фильтры
   */
  onFiltersChanged: (filters: FilterState[]) => void;

  /**
   * Вызывается при применении фильтра.
   * @param {FilterState} filter - Примененный фильтр
   */
  onFilterApplied: (filter: FilterState) => void;

  /**
   * Вызывается при удалении фильтра.
   * @param {string} filterId - ID удаленного фильтра
   */
  onFilterRemoved: (filterId: string) => void;

  /**
   * Вызывается при обновлении товаров.
   * @param {FullProduct[]} products - Обновленные товары
   */
  onProductsUpdated: (products: FullProduct[]) => void;

  /**
   * Вызывается при выборе товара.
   * @param {FullProduct} product - Выбранный товар
   */
  onProductSelected: (product: FullProduct) => void;
}

/**
 * Интерфейс конфигурации для управления общим состоянием.
 * Определяет поведение и настройки для межвиджетного взаимодействия.
 */
export interface SharedStateConfig {
  /**
   * Автоматически обновлять результаты поиска при изменении фильтров.
   * @defaultValue true
   */
  autoUpdateOnFilterChange?: boolean;

  /**
   * Конфигурация API для операций общего состояния.
   */
  api?: {
    /**
     * Базовый URL для API запросов.
     */
    baseUrl?: string;
    /**
     * Токен аутентификации.
     */
    token?: string;
    /**
     * Идентификатор клиента.
     */
    customerId?: string;
    /**
     * Идентификатор локации.
     */
    locationId?: string;
    /**
     * Версия API для использования.
     * @defaultValue "v1"
     */
    apiVersion?: string;
  };

  /**
   * Специфичная конфигурация поискового виджета.
   */
  searchWidget?: {
    /**
     * Текст-заполнитель для поля поиска.
     * @defaultValue "Поиск товаров..."
     */
    placeholder?: string;
    /**
     * Задержка для поля ввода поиска.
     * @defaultValue 300
     */
    debounceMs?: number;
    /**
     * Минимальные символы для поиска.
     * @defaultValue 2
     */
    minSearchLength?: number;
    /**
     * Включить темную тему.
     * @defaultValue false
     */
    darkMode?: boolean;
    /**
     * Включить стили режима фокуса.
     * @defaultValue false
     */
    focusMode?: boolean;
    /**
     * Показывать кнопку очистки.
     * @defaultValue true
     */
    showClearButton?: boolean;
  };

  /**
   * Специфичная конфигурация виджета фильтров.
   */
  filtersWidget?: {
    /**
     * Максимальное количество значений на фильтр для отображения.
     * @defaultValue 5
     */
    maxValuesPerFilter?: number;
    /**
     * Задержка для изменений фильтров.
     * @defaultValue 300
     */
    debounceMs?: number;
    /**
     * Включить темную тему.
     * @defaultValue false
     */
    darkMode?: boolean;
  };

  /**
   * Специфичная конфигурация виджета товаров.
   */
  productsWidget?: {
    /**
     * Количество товаров на странице.
     * @defaultValue 20
     */
    itemsPerPage?: number;
    /**
     * Ширина элемента сетки на мобильных устройствах.
     * @defaultValue 140
     */
    mobileItemWidth?: number;
    /**
     * Ширина элемента сетки на десктопе.
     * @defaultValue 250
     */
    desktopItemWidth?: number;
    /**
     * Включить темную тему.
     * @defaultValue false
     */
    darkMode?: boolean;
    /**
     * Показывать элементы управления пагинацией.
     * @defaultValue true
     */
    showPagination?: boolean;
    /**
     * Показывать общее количество.
     * @defaultValue true
     */
    showTotalCount?: boolean;
  };

  /**
   * Специфичная конфигурация виджета сортировки.
   */
  sortWidget?: {
    /**
     * Включить темную тему.
     * @defaultValue false
     */
    darkMode?: boolean;
    /**
     * Опция сортировки по умолчанию.
     * @defaultValue "relevance"
     */
    defaultSort?: string;
  };
}