plugin-ui-for-kzt 0.0.9 → 0.0.10

package/src/components/BaseCheckbox/README.md

@@ -0,0 +1,110 @@
+### BaseCheckbox
+
+Компонент для создания флажка (чекбокса) с поддержкой состояния "выбран" и "не выбран". Он может быть использован для выбора одного или нескольких значений в форме или списке.
+
+---
+
+#### Props
+
+- `id: string`  
+  Идентификатор элемента чекбокса. Используется для связывания с меткой.
+
+- `modelValue: boolean`  
+  Состояние чекбокса, которое управляется через двустороннюю привязку. Если `true`, чекбокс активен (выбран).
+
+- `name?: string`  
+  Имя чекбокса, полезно для группировки чекбоксов в форме.
+
+- `label?: string`  
+  Основной текст, который отображается рядом с чекбоксом.
+
+- `subLabel?: string`  
+  Дополнительный текст, который отображается под основным лейблом.
+
+- `labelPosition?: 'left' | 'right'`  
+  Определяет, с какой стороны будет отображаться текст метки: слева или справа от чекбокса.
+
+- `readonly?: boolean`  
+  Если `true`, чекбокс становится только для чтения и не реагирует на клики.
+
+- `size: 'small' | 'medium'`  
+  Размер чекбокса. Может быть `'small'` или `'medium'`.
+
+---
+
+#### Важные особенности
+
+- **Управление состоянием:**  
+  Состояние чекбокса управляется с помощью двусторонней привязки через `modelValue`. Когда значение меняется, это событие передаётся через `update:modelValue`.
+
+- **Анимация:**  
+  При активировании чекбокса появляется анимация для иконки, которая представляет галочку. Эта анимация плавно появляется с увеличением масштаба и исчезает, когда чекбокс неактивен.
+
+- **Адаптивность:**  
+  Чекбокс поддерживает два размера: `small`, `medium` и `large`, каждый из которых имеет свою стилизацию для иконки и текста.
+
+- **Состояния:**  
+  Компонент поддерживает разные состояния, такие как `readonly` (чекбокс только для чтения), а также стандартные состояния активности (открытый/закрытый).
+
+---
+
+#### Пример использования
+
+```vue
+<BaseCheckbox v-model="isChecked" label="Accept terms and conditions" size="small">
+  <template #label>
+    <span>Agree to terms</span>
+  </template>
+</BaseCheckbox>
+```
+
+---
+
+#### Логика
+
+- **Переключение состояния:**  
+  При клике на чекбокс вызывается функция `handleToggle`, которая инвертирует состояние чекбокса (`model.value`).
+
+- **Передача атрибутов:**  
+  Чекбокс принимает дополнительные атрибуты через `attrs`, которые могут быть переданы родительским компонентом (например, `id`, `disabled`).
+
+- **Классы для стилей:**  
+  Классы для разных состояний и размеров генерируются с использованием композиционных функций `useKitSize` и `useKitState`.
+
+---
+
+#### Стилизация
+
+- **Иконка чекбокса:**  
+  Иконка чекбокса представляет собой стандартную галочку, которая появляется при активации. Её анимация включает плавное увеличение и появление.
+
+- **Стили для состояния "disabled":**  
+  Когда чекбокс находится в состоянии "disabled", его внешний вид изменяется, а взаимодействие с ним блокируется.
+
+- **Мелкие и крупные размеры:**  
+  Для разных размеров чекбокса изменяются размеры иконки, текстов и общая компоновка.
+
+---
+
+#### Стили для состояний
+
+```scss
+.base-checkbox.--is-active {
+  .base-checkbox__icon-wrapper {
+    background: var(--primary-blue-50);
+    border-color: var(--primary-blue);
+  }
+
+  .base-checkbox__icon {
+    opacity: 1;
+    transform: translate(-50%, -50%) scale(1);
+    animation: checkmark-appear 0.3s ease-out forwards;
+  }
+}
+```
+
+Эти стили отвечают за активное состояние чекбокса. Иконка и обводка меняются, а также добавляется анимация появления галочки. 
+
+---
+
+Этот компонент подходит для создания чекбоксов с гибкими возможностями для стилизации и управления состоянием в рамках различных интерфейсов.

package/src/components/BaseDropdown/BaseDropdown.vue

@@ -0,0 +1,160 @@
+<template>
+    <div class="dropdown" :class="[classList]">
+        <div
+            ref="wrapperRef"
+            class="dropdown__wrapper"
+        >
+            <div
+                ref="topRef"
+                tabindex="0"
+                class="dropdown__top"
+                @click.prevent.stop="() => onToggle()"
+                @keydown.enter="handleEnterKey"
+            >
+                <slot name="top" />
+            </div>
+
+            <transition
+                :name="transitionName || 'default-transition'"
+                mode="out-in"
+            >
+                <div
+                    v-if="isOpened"
+                    :style="dropdownStyleList"
+                    class="dropdown__dropdown"
+                    @click="handleDropdownClick"
+                >
+                    <slot name="dropdown" />
+                </div>
+            </transition>
+        </div>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { onClickOutside, useElementBounding } from '@vueuse/core';
+import type { ICoreDropdownProps } from '../../types/dropdown';
+import { useKitSize } from '../../composables/kit/size'
+import { useKitState } from '../../composables/kit/state'
+
+type TModelValue = boolean;
+
+const props = withDefaults(defineProps<ICoreDropdownProps>(), {
+  size: 'medium',
+  color: 'primary',
+});
+const emit = defineEmits<{
+  'update:modelValue': [value: TModelValue]
+}>();
+
+const model = computed({
+  get: () => props.modelValue,
+  set: (val) => emit('update:modelValue', val),
+});
+
+
+const { sizeClassList } = useKitSize(props);
+const { stateClassList } = useKitState(props);
+
+const wrapperRef = ref<HTMLDivElement>();
+const topRef = ref<HTMLDivElement>();
+const { width: topWidth } = useElementBounding(topRef);
+
+const isOpened = ref<TModelValue>(false);
+
+const dropdownStyleList = computed(() => ({
+  ...(props.parentWidth && {
+    width: `${topWidth.value}px`,
+  }),
+}));
+
+const transitionName = computed(() => props.transitionName || 'fade');
+
+function onToggle(value?: TModelValue, immediate?: boolean) {
+  if ((props.preventControl || props.disabled) && !immediate) {
+    return false;
+  }
+
+  const newValue = typeof value === 'undefined' ? !isOpened.value : value;
+
+  if (!props.preventControl || immediate) {
+    isOpened.value = newValue;
+  }
+
+  emit('update:modelValue', newValue);
+}
+
+function handleEnterKey(event: KeyboardEvent) {
+  if (event.code === 'Enter') {
+    onToggle();
+  }
+}
+
+function handleDropdownClick() {
+  if (props.autoClose) {
+    onToggle(false);
+  }
+}
+
+watch(
+  () => model.value,
+  (val) => {
+    onToggle(val, true);
+  },
+  {
+    immediate: true,
+  },
+);
+
+onClickOutside(wrapperRef, () => {
+  onToggle(false, true);
+});
+
+const classList = computed(() => [
+  sizeClassList.value,
+  stateClassList.value,
+
+  {
+    '--is-opened': isOpened.value,
+  },
+]);
+</script>
+
+<style scoped lang="scss">
+  @import '../../styles/variables';
+  @import '../../styles/root';
+
+.dropdown {
+    &__wrapper {
+        position: relative;
+        width: 100%;
+        height: 100%;
+    }
+
+    &__top {
+        cursor: pointer;
+        outline: none;
+    }
+
+    &__dropdown {
+      position: absolute;
+      z-index: 3;
+      margin-top: var(--spacing-s);
+      overflow-x: hidden;
+      overflow-y: auto;
+      width: 280px;
+      height: auto;
+      max-height: 320px;
+      background: var(--bg-light);
+      padding: var(--spacing-xs) 0;
+      border: 1px solid var(--primary-black-100);
+      border-radius: var(--corner-radius-m);
+      box-shadow: 0px 4px 6px -2px var(--effects-dropdown-shadows-100);
+
+      @include scrollbar;
+    }
+
+    @include is-disabled-state;
+}
+</style>

package/src/components/BaseDropdown/README.md

@@ -0,0 +1,91 @@
+### BaseDropdown
+
+Компонент для создания выпадающего списка, который можно контролировать с помощью пропсов и событий. Он поддерживает открытие и закрытие списка, а также различные стили и размеры.
+
+---
+
+#### Props
+
+- `size: string`  
+  Размер компонента. Может быть `'small'`, `'medium'` или `'large'`. По умолчанию используется `'medium'`.
+
+- `modelValue: boolean`  
+  Состояние открытия/закрытия выпадающего списка. Это двусторонняя привязка. Управляется внешним компонентом.
+
+- `parentWidth: boolean`  
+  Устанавливает ширину выпадающего списка, равную ширине элемента, на который наведен фокус.
+
+- `transitionName: string`  
+  Название анимации для перехода. По умолчанию используется `'fade'`.
+
+- `autoClose: boolean`  
+  Определяет, должен ли список закрываться автоматически при клике внутри него. По умолчанию это включено.
+
+- `disabled: boolean`  
+  Определяет, может ли компонент быть активным. Если `true`, компоненты не будут взаимодействовать.
+
+- `preventControl: boolean`  
+  Устанавливает, можно ли вручную контролировать состояние открытия/закрытия компонента. Если установлено в `true`, то компоненты будут использовать только внутреннее состояние.
+
+---
+
+#### Важные особенности
+
+- **Управление состоянием:**  
+  Состояние открытия/закрытия контролируется через `modelValue`, что позволяет родительскому компоненту управлять этим состоянием. Однако также можно использовать внутреннее состояние через `isOpened`.
+
+- **Анимации:**  
+  Компонент поддерживает анимации перехода через свойство `transitionName`. По умолчанию используется плавное исчезновение.
+
+- **Закрытие при клике вне:**  
+  Если компонент открыт, он автоматически закроется при клике вне его области (с помощью `onClickOutside`).
+
+- **Поддержка размеров:**  
+  Размер компонента управляется через проп `size` с использованием CSS-классов для различных размеров.
+
+---
+
+#### Пример использования
+
+```vue
+<BaseDropdown v-model="isOpen" size="small">
+  <template #top>
+    <button>Click to toggle dropdown</button>
+  </template>
+
+  <template #dropdown>
+    <ul>
+      <li>Option 1</li>
+      <li>Option 2</li>
+      <li>Option 3</li>
+    </ul>
+  </template>
+</BaseDropdown>
+```
+
+---
+
+#### Логика
+
+- **Открытие/закрытие:**  
+  Функция `onToggle` контролирует открытие/закрытие выпадающего списка. Она может быть вызвана при клике на элемент или по нажатию клавиши Enter.
+
+- **Автозакрытие:**  
+  При клике на выпадающий список или на элемент внутри него (если `autoClose` истинно) список будет закрываться.
+
+- **Обработчик клавиши Enter:**  
+  При нажатии клавиши `Enter` срабатывает функция `onToggle`, открывая или закрывая выпадающий список.
+
+---
+
+#### Стилизация
+
+- **Позиционирование:**  
+  Выпадающий список позиционируется относительно родительского элемента с использованием абсолютного позиционирования.
+
+- **Активные/неактивные состояния:**  
+  Включены стили для отображения состояния компонента, когда он в состоянии "disabled" или когда выпадающий список открыт.
+
+---
+
+Компонент идеально подходит для реализации выпадающих меню, селекторов или других интерфейсов, где необходимо управлять открытием и закрытием элементов через UI-элементы.

package/src/components/BaseIcon/BaseIcon.vue

@@ -0,0 +1,47 @@
+<template>
+    <svg class="base-icon" :class="sizeClassList"  aria-hidden="true">
+      <use :xlink:href="`#${name}`" />
+    </svg>
+</template>
+  
+<script setup lang="ts">
+  import type { TIconProps } from "../../types/icon";
+  import { useKitSize } from '../../composables/kit/size'
+  
+  const props = withDefaults(defineProps<TIconProps>(), {
+    size: 'medium',
+  });
+  const { sizeClassList } = useKitSize(props);
+</script>
+
+<style lang="scss" scoped>
+ @import '../../styles/variables';
+ @import '../../styles/root';
+
+  .base-icon {
+    display: block;
+    width: 100%;
+    height: 100%;
+    fill: currentColor;
+
+    &.--extra-small-size {
+      width: 20px;
+      height: 20px;
+    }
+
+    &.--small-size {
+      width: 20px;
+      height: 20px;
+    }
+
+    &.--medium-size {
+      width: 24px;
+      height: 24px;
+    }
+
+    &.--large-size {
+      width: 32px;
+      height: 32px;
+    }
+  }
+</style>

package/src/components/BaseIcon/README.md

@@ -0,0 +1,35 @@
+### BaseIcon
+
+Компонент для отображения иконок в формате SVG. Используется для отображения иконок через ссылку на SVG-спрайт.
+
+---
+
+#### Props
+
+- `name: string`  
+  Имя иконки, которое будет использовано для отображения соответствующего символа из спрайта. Это обязательный параметр.
+
+- `size: 'small' | 'medium' | 'large' | 'custom'`  
+  Размер компонента. Определяет размеры иконок и поля ввода. По умолчанию — `medium`.
+
+---
+
+#### Важные особенности
+
+- **Динамическое изменение размера:**  
+  Размер иконки можно контролировать через проп `size`, что позволяет использовать компонент с разными размерами без необходимости изменения стилей.
+
+- **SVG-спрайт:**  
+  Иконка загружается из спрайта, используя атрибут `xlink:href`, ссылаясь на иконку по её имени. Это предполагает использование SVG спрайтов, где каждая иконка хранится внутри одного файла.
+
+---
+
+#### Пример использования
+
+```vue
+<BaseIcon name="calendar" size="small" />
+```
+
+---
+
+Компонент подходит для отображения иконок с гибкими параметрами, что полезно в контексте интерфейсов, где необходимо обеспечить гибкость в отображении иконок (например, в кнопках или формах).