@topvisor/ui 1.0.42-checkvisibility.3 → 1.0.42-dev.1

package/src/components/formsExt/selector2/stories/README.md

@@ -0,0 +1,146 @@
+## Универсальный компонент выбора значений из списка
+
+**TopSelector2** — это гибкий компонент для выбора одного или нескольких значений из списка. Компонент поддерживает различные режимы работы, поиск,
+загрузку данных через API и кастомизацию внешнего вида.
+
+## Стандартная функциональность
+
+- Выбор одного значения из списка (режим по умолчанию)
+- Выбор нескольких значений из списка (режим `multiselect`)
+- Поиск по элементам списка (режимы `inline` и `popup`)
+- Загрузка данных через API с поддержкой пагинации и кэширования
+- Поддержка клавиатурной навигации
+- Кастомизация внешнего вида (размер, стиль кнопки)
+- Возможность добавления пользовательских значений
+
+## Режимы работы
+
+### Режимы выбора
+
+- **Single select** (по умолчанию): Выбор одного значения из списка
+- **Multi select** (`multiselect: true`): Выбор нескольких значений из списка с отображением выбранных элементов в виде тегов
+
+### Режимы поиска
+
+- **none**: Без поиска
+- **inline**: Поле ввода встроено в сам селектор (только для `multiselect: false`)
+- **popup**: Поиск в отдельном поле внутри всплывающего окна
+
+В мобильной версии режим `inline` автоматически заменяется на `popup`.
+
+## Уникальные возможности
+
+- Возможность добавления опции "Все" (`appendAllValue: true`)
+- Возможность добавления пользовательских значений (`appendSearchToResult: true`)
+- Кнопка быстрого переключения между значениями (`addChanger: true`)
+- Стилизация в виде кнопки (`buttonProps`)
+- Поддержка кастомного рендеринга элементов через слот `item`
+- Загрузка данных через API с поддержкой пагинации и кэширования
+- Автоматическая адаптация под мобильные устройства
+
+## Примеры использования
+
+### Простой селектор
+
+```html
+
+<Selector2
+	v-model="selectedItem"
+	:items="itemsList"
+/>
+```
+
+### Селектор с возможностью указать своё значение
+
+```html
+
+<Selector2
+	v-model="selectedItem"
+	:items="itemsList"
+	:appendSearchToResult="true"
+/>
+```
+
+### Селектор с выбором "Все"
+
+```html
+
+<Selector2
+	v-model="selectedItem"
+	:items="itemsList"
+	:appendAllValue="true"
+/>
+```
+
+### Мультиселектор
+
+```html
+
+<Selector2
+	v-model="selectedItems"
+	:items="itemsList"
+	:multiselect="true"
+/>
+```
+
+### Селектор с загрузкой данных через API
+
+```html
+
+<Selector2
+	v-model="selectedItem"
+	:apiRequest="apiRequestConfig"
+	:minLength="2"
+/>
+```
+
+### Селектор в виде кнопки
+
+```html
+
+<Selector2
+	v-model="selectedItem"
+	:items="itemsList"
+	:buttonProps="{
+    color: 'theme',
+    styling: 'soft'
+  }"
+/>
+```
+
+## Работа с API
+
+Для загрузки данных через API необходимо передать объект `apiRequest` со следующей структурой:
+
+```js
+const apiRequest = {
+	params: {
+		offset: 0,      // смещение для пагинации
+		limit: 100,     // количество элементов на странице
+		search: '',     // строка поиска
+	},
+	cache: new Map(), // кэш результатов
+	call: async function () {
+		// функция для выполнения запроса
+		// должна возвращать объект { result: Array<Item>, nextOffset?: number }
+	}
+};
+```
+
+## Кастомизация отображения элементов
+
+Для кастомизации отображения элементов списка можно использовать слот `item`:
+
+```html
+
+<Selector2
+	v-model="selectedItem"
+	:items="itemsList"
+>
+	<template #item="{ item }">
+		<div :title="'id: ' + item.id">
+			{{ item.name }}
+		</div>
+	</template>
+</Selector2>
+```

package/src/components/formsExt/selector2/stories/dummyAPIRequest.ts

@@ -0,0 +1,57 @@
+import { invertKeyboardLayout } from '@/core/utils/keyboard';
+import type { Item } from '../types';
+
+const dummyAPIRequestItems: Item[] = [];
+
+for (let i = 10; i < 300; i++) {
+	const id = i + 1;
+	dummyAPIRequestItems.push({
+		id,
+		name: `Запись #${id}`,
+	});
+}
+
+export const dummyAPIRequest = {
+	params: {
+		offset: undefined,
+		limit: undefined,
+		search: '',
+	},
+
+	cache: new Map(),
+
+	async call() {
+		console.log('dummyAPIRequest call()');
+
+		const offset = this.params.offset ?? 0;
+		const limit = this.params.limit ?? 100;
+		const searchString = this.params.search?.toLowerCase();
+		const searchStringInvertKeyboard = invertKeyboardLayout(searchString);
+
+		const filterItems = dummyAPIRequestItems.filter(item => {
+			if (!searchString) return true;
+
+			const itemName = item.name.toLowerCase();
+
+			return (
+				item.id === Number(searchString)
+				|| itemName.includes(searchString)
+				|| itemName.includes(searchStringInvertKeyboard)
+			);
+		});
+
+		const result = filterItems.slice(offset, offset + limit);
+
+		return new Promise(resolve => {
+			const res: { result: Array<any>, nextOffset?: number } = {
+				result,
+			};
+
+			const nextOffset = offset + limit;
+
+			if (nextOffset < filterItems.length) res.nextOffset = nextOffset;
+
+			setTimeout(() => resolve(res), 500);
+		});
+	},
+};

package/src/components/formsExt/selector2/stories/overview.vue

@@ -0,0 +1,95 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import Selector2 from '../selector2.vue';
+import type { Item, Props } from '../types';
+import { dummyAPIRequest } from './dummyAPIRequest';
+
+defineProps<Props>();
+
+defineModel<Props['modelValue']>();
+
+const items: Props['items'] = [
+	{
+		id: 1,
+		name: 'Выбери меня',
+	},
+	{
+		id: 2,
+		name: 'И меня',
+	},
+	{
+		id: 3,
+		name: 'И меня тоже',
+	},
+] as Item[];
+
+const item = {
+	id: null,
+	name: '',
+};
+
+const selector_1 = ref(item);
+const selector_2 = ref(item);
+const selector_3 = ref(item);
+const selector_4 = ref([]);
+const selector_5 = ref(item);
+const selector_6 = ref([]);
+</script>
+
+<template>
+	<div>
+		<h2>Простой Selector</h2>
+
+		<Selector2
+			:=$props
+			v-model="selector_1"
+			:items="items"
+		/>
+
+		<h2>Selector с возможностью указать свое значение</h2>
+
+		<Selector2
+			:=$props
+			v-model="selector_2"
+			:items
+			:appendSearchToResult="true"
+		/>
+
+		<h2>Selector с выбором Все</h2>
+
+		<Selector2
+			:=$props
+			v-model="selector_3"
+			:items
+			:appendAllValue="true"
+		/>
+
+		<h2>Selector (multiselector = true)</h2>
+
+		<Selector2
+			:=$props
+			v-model="selector_4"
+			:items
+			:multiselect="true"
+		/>
+
+		<h2>Selector ajax (multiselector = false, minLength = 2)</h2>
+
+		<Selector2
+			:=$props
+			v-model="selector_5"
+			:apiRequest="dummyAPIRequest"
+			:minLength="2"
+		/>
+
+		<h2>Selector ajax (multiselector = true, minLength = 2)</h2>
+
+		<Selector2
+			:=$props
+			v-model="selector_6"
+			:apiRequest="dummyAPIRequest"
+			:multiselect="true"
+			:minLength="2"
+		/>
+	</div>
+</template>

package/src/components/formsExt/selector2/types.ts

@@ -0,0 +1,184 @@
+import type { Size } from '@/components/forms/helpers';
+import type { Props as ButtonProps } from '@/components/forms/button/types';
+
+export interface Props {
+	/**
+	 * Выбранный элемент
+	 *
+	 * Массив выбранных элементов, если multiselect = true
+	 */
+	modelValue: Item | Item[];
+
+	/**
+	 * Список вариантов для выбора
+	 *
+	 * При работе с apiRequest, всегда выводится перед результатами apiRequest
+	 */
+	items?: Item[];
+
+	title?: string
+	disabled?: boolean;
+
+	/**
+	 * Модификатор элемента, открывающего popup
+	 *
+	 * Добавит класс: `top-selector2-{{ modificator }}`
+	 */
+	modificator?: string;
+
+	size?: Size;
+	isError?: boolean;
+
+	/**
+	 * Тип поиска по элементам
+	 *
+	 * - none: без поиска
+	 * - inline: сам Selector является полем ввода, только для `multiselect = false`
+	 * - popup: поиск будет в popup
+	 *
+	 * Для мобильной версии `inline` всегда заменяется на `popup`
+	 *
+	 * Константа, после установки менять нельзя
+	 */
+	searchType?: 'none' | 'inline' | 'popup',
+
+	/**
+	 * Текст для placeholder поля поиска
+	 */
+	placeholder?: string;
+
+	/**
+	 * Если указан, будет выполнена загрузка результатов через API
+	 *
+	 * Константа, после установки заменять нельзя
+	 *
+	 * @subcategory apiRequest
+	 */
+	apiRequest?: {
+		params: {
+			limit?: number,
+			offset?: number,
+			search?: string,
+		};
+		call: Function;
+		cache: Map<string, { result: Array<Item>, nextOffset?: number }>;
+
+		[propName: string]: any;
+	};
+
+	/**
+	 * Минимальная длина для выполнения поиска
+	 *
+	 * Константа, после установки менять нельзя
+	 *
+	 * @subcategory apiRequest
+	 */
+	minLength?: number;
+
+	/**
+	 * Использовать кэширование
+	 *
+	 * Константа, после установки менять нельзя
+	 *
+	 * @subcategory apiRequest
+	 */
+	useCache?: boolean;
+
+	/**
+	 * Добавить в результаты item = {id:null, name:search}, где search - введенная строка в поле поиска
+	 */
+	appendSearchToResult?: boolean;
+
+	/**
+	 * Режим выбора нескольких вариантов
+	 *
+	 * Константа, после установки менять нельзя
+	 *
+	 * @subcategory Multiselect
+	 */
+	multiselect?: boolean;
+
+	/**
+	 * Добавить вариант: "Все"
+	 *
+	 * @subcategory Single select
+	 */
+	appendAllValue?: boolean;
+
+	/**
+	 * Отобразить кнопку смены значения
+	 *
+	 * Работает с props.items без учета apiRequest
+	 *
+	 * Нельзя использовать с кнопкой
+	 *
+	 * @subcategory Single select
+	 */
+	addChanger?: boolean;
+
+	/**
+	 * Настройки кнопки
+	 *
+	 * Если не указан будет использоваться стандартный стиль селектора
+	 *
+	 * @subcategory Single select
+	 */
+	buttonProps?: ButtonProps,
+
+	/**
+	 * Выводить в placeholder поля поиска выбранное значение `modelValue.name`
+	 *
+	 * Всегда включено для `searchType` = `inline`
+	 *
+	 * @subcategory Single select
+	 */
+	selectedAsPlaceholder?: boolean;
+}
+
+export interface Slots {
+	/**
+	 * Шаблон для генерации элементов списка результатов
+	 *
+	 * Принимает параметр item: Type
+	 *
+	 * Если шаблон не указан будет выводиться item.name
+	 *
+	 * Пример:
+	 *
+	 * ```html
+	 * <div :title="'id: ' + item.id">
+	 *     {{ item.name }}
+	 * </div>
+	 * ```
+	 */
+	item?(props: { item: Item }): any;
+}
+
+export interface PropsItemMulti {
+	id: Item['id'],
+	name: Item['name'],
+}
+
+export type EmitsItemMulti = {
+	/**
+	 * Удалить выбранный элемент
+	 */
+	delete: [id: Item['id']]
+}
+
+/**
+ * Элемент, который можно выбрать в Selector
+ */
+export interface Item {
+	/**
+	 * id объекта
+	 *
+	 * Если null - объект для добавления, не имеет свой id
+	 */
+	id: number | null;
+	name: string;
+
+	[propName: string]: any;
+}
+
+export type { Size };

package/src/components/formsExt/selector2/utils.ts

@@ -0,0 +1,22 @@
+import type { Item, Props } from './types';
+
+export const ITEM_ID_ALL = 0;
+
+/**
+ * Выбран ли элемент
+ */
+export const isSelected = (modelValue: Props['modelValue'], item: Item, checkNameForNullId = true) => {
+	if (checkNameForNullId && item.id === null) {
+		if (Array.isArray(modelValue)) {
+			return modelValue.some(itemSelected => itemSelected.id === item.id && itemSelected.name === item.name);
+		} else {
+			return item.name === modelValue.name;
+		}
+	}
+
+	if (Array.isArray(modelValue)) {
+		return modelValue.some(itemSelected => itemSelected.id === item.id);
+	} else {
+		return item.id === modelValue.id;
+	}
+};