alex-evo-sh-ui-kit 1.1.2 → 1.1.3

package/docs/BaseActionCard.md

@@ -0,0 +1,24 @@
+# Компонент BaseActionCard (Legacy)
+
+Базовый компонент-контейнер для размещения действий (кнопок, ссылок и других интерактивных элементов). 
+
+## Внешний вид  
+
+![BaseActionCard](img/BaseActionCard.png)
+
+## Props (Свойства)
+
+| Свойство | Тип | Описание | По умолчанию |
+|----------|-----|----------|--------------|
+| `children` | `React.ReactNode` | Дочерние элементы (обычно кнопки или другие интерактивные элементы) | - |
+| `className` | `string` | Дополнительные CSS-классы для кастомизации | - |
+
+## Пример использования
+
+```jsx
+<BaseActionCard className="custom-actions">
+  <Button>Сохранить</Button>
+  <Button variant="outlined">Отмена</Button>
+  <Link href="/help">Помощь</Link>
+</BaseActionCard>
+```

package/docs/BaseDialog.md

@@ -0,0 +1,109 @@
+# Документация компонента BaseDialog
+
+## Обзор
+`BaseDialog` - это универсальный диалоговый компонент для отображения подтверждений, уведомлений и произвольного контента. Поддерживает стандартные и кастомные кнопки действий.
+
+## Внешний вид  
+
+![BaseDialog](img/BaseDialog.png)
+
+## Пропсы
+
+### Основные пропсы
+| Проп                 | Тип                     | По умолчанию | Описание                                                                 |
+|----------------------|-------------------------|--------------|-------------------------------------------------------------------------|
+| `text`               | string                  | -            | Текст сообщения в диалоге                                              |
+| `header`             | string                  | -            | Заголовок диалога                                                      |
+| `actionText`         | string                  | "OK"         | Текст на кнопке действия                                               |
+| `cancelText`         | string                  | "Отмена"     | Текст на кнопке отмены                                                 |
+| `onSuccess`          | function                | -            | Колбек при подтверждении                                               |
+| `onCancel`           | function                | -            | Колбек при отмене                                                      |
+| `onHide`             | function                | -            | Колбек при закрытии (вызывается всегда)                                |
+| `styleContainer`     | React.CSSProperties     | -            | Стили контейнера диалога                                               |
+| `children`           | React.ReactNode         | -            | Дополнительный контент вместо текста                                   |
+| `disableDefaultButtons` | boolean              | false        | Отключить стандартные кнопки                                           |
+| `customActions`      | React.ReactNode         | -            | Кастомные кнопки действий                                              |
+
+## Примеры использования
+
+### Простой диалог подтверждения
+```jsx
+<BaseDialog
+  header="Подтверждение удаления"
+  text="Вы уверены, что хотите удалить этот элемент?"
+  actionText="Удалить"
+  cancelText="Отменить"
+  onSuccess={handleDelete}
+  onCancel={handleCancel}
+/>
+```
+
+### Диалог с кастомным контентом
+```jsx
+<BaseDialog 
+  header="Настройки"
+  onHide={closeDialog}
+>
+  <div className="custom-content">
+    {/* Кастомный контент */}
+  </div>
+</BaseDialog>
+```
+
+### Диалог с кастомными кнопками
+```jsx
+<BaseDialog
+  header="Специальные действия"
+  text="Выберите действие:"
+  disableDefaultButtons
+  customActions={
+    <div className="custom-actions">
+      <Button onClick={action1}>Действие 1</Button>
+      <Button onClick={action2}>Действие 2</Button>
+    </div>
+  }
+/>
+```
+
+## Особенности работы
+
+1. **Обработка событий**:
+   - `onSuccess` вызывается при подтверждении (клик по action кнопке)
+   - `onCancel` вызывается при отмене (клик по cancel кнопке)
+   - `onHide` вызывается в любом случае при закрытии диалога
+
+2. **Кастомизация**:
+   - Можно полностью заменить стандартные кнопки через `customActions`
+   - Можно отключить стандартные кнопки (`disableDefaultButtons`)
+   - Поддерживается как простой текст (`text`), так и сложный контент (`children`)
+
+3. **Композиция**:
+   - Использует `BasicTemplateDialog` как базовый шаблон
+   - Кнопки реализованы как отдельный компонент `BaseDialogButton`
+
+## Рекомендации по использованию
+
+1. Для простых подтверждений используйте пропсы `text`, `actionText`, `cancelText`
+2. Для сложных сценариев используйте `children` и `customActions`
+3. Всегда обрабатывайте `onHide` для корректного закрытия диалога
+4. Для управления состоянием диалога используйте внешний стейт
+
+```jsx
+// Пример управления видимостью
+const [isOpen, setIsOpen] = useState(false);
+
+const handleClose = () => setIsOpen(false);
+
+return (
+  <>
+    <Button onClick={() => setIsOpen(true)}>Открыть диалог</Button>
+    {isOpen && (
+      <BaseDialog
+        header="Пример"
+        text="Пример сообщения"
+        onHide={handleClose}
+      />
+    )}
+  </>
+);
+```

package/docs/BigContainer.md

@@ -0,0 +1,81 @@
+# Документация BigContainer
+
+## Обзор
+
+Компонент `BigContainer` представляет собой контейнер с возможностью перетаскивания содержимого с помощью средней кнопки мыши (обычно нажатие колесика).
+
+## Основные возможности
+
+- Перетаскивание содержимого средней кнопкой мыши
+- Настраиваемые размеры контейнера
+- Управление позицией через пропсы
+- Опциональное отключение перетаскивания
+
+## Пропсы
+
+| Пропс | Тип | По умолчанию | Описание |
+|-------|-----|-------------|-----------|
+| `children` | `React.ReactNode` | - | Дочерние элементы для отображения внутри контейнера |
+| `className` | `string` | `''` | Дополнительный CSS-класс для контейнера |
+| `height` | `string` | `'100%'` | Высота контейнера |
+| `width` | `string` | `'100%'` | Ширина контейнера |
+| `id` | `string` | - | HTML-атрибут ID для контейнера |
+| `pozMove` | `IPoint` | `{x:0,y:0}` | Начальная/управляемая позиция содержимого (координаты x, y) |
+| `draggable` | `boolean` | `true` | Включает/отключает возможность перетаскивания |
+
+## Типы
+
+```typescript
+interface IPoint {
+  x: number; // координата по горизонтали
+  y: number; // координата по вертикали
+}
+```
+
+## Примеры использования
+
+### Базовое использование
+
+```jsx
+<BigContainer height="300px" width="500px">
+  <div style={{ padding: '20px' }}>
+    Содержимое, которое можно перетаскивать средней кнопкой мыши
+  </div>
+</BigContainer>
+```
+
+### С начальной позицией
+
+```jsx
+<BigContainer 
+  height="400px" 
+  width="600px"
+  pozMove={{ x: 50, y: 50 }}
+>
+  <div style={{ padding: '20px', backgroundColor: '#f0f0f0' }}>
+    Содержимое начинается с позиции (50, 50)
+  </div>
+</BigContainer>
+```
+
+### Без возможности перетаскивания
+
+```jsx
+<BigContainer 
+  height="300px" 
+  width="500px"
+  draggable={false}
+>
+  <div style={{ padding: '20px' }}>
+    Это содержимое нельзя перетаскивать
+  </div>
+</BigContainer>
+```
+
+## Поведение компонента
+
+- Отслеживает нажатие средней кнопки мыши (код кнопки 1)
+- При начале перетаскивания курсор меняется на 'move'
+- После окончания перетаскивания курсор возвращается в стандартное состояние
+- Позиция содержимого может управляться извне через пропс `pozMove`
+- Перетаскивание можно полностью отключить пропсом `draggable`

package/docs/BottomSheetsUi.md

@@ -0,0 +1,55 @@
+
+
+
+# BottomSheetsUi
+
+`BottomSheetsUi` — это компонент, реализующий выезжающее снизу модальное окно (Bottom Sheet) с возможностью закрытия через свайп или клик.
+
+## Внешний вид
+
+![BottomSheetsUi](img/BottomSheetsUi.png)
+
+## Свойства
+
+| Свойство  | Тип                    | Описание  |
+|-----------|------------------------|------------------------------------------------------------------------------------------------------------|
+| `onHide`  | `() => void`           | Колбэк, вызываемый при закрытии Bottom Sheet. |
+| `visible` | `boolean`              | Определяет, отображается ли Bottom Sheet. |
+| `children` | `React.ReactNode` (необяз.) | Контент, который будет внутри Bottom Sheet. |
+| `bottom`  | `number` (необяз.)      | Отступ снизу (по умолчанию `0`). |
+
+## Использование
+
+```tsx
+import { BottomSheetsUi } from "./BottomSheetsUi";
+import { useState } from "react";
+
+const App = () => {
+    const [isOpen, setIsOpen] = useState(false);
+
+    return (
+        <div>
+            <button onClick={() => setIsOpen(true)}>Открыть Bottom Sheet</button>
+            <BottomSheetsUi visible={isOpen} onHide={() => setIsOpen(false)}>
+                <div className="bottom-sheet-content">
+                    <h2>Пример Bottom Sheet</h2>
+                    <button onClick={() => setIsOpen(false)}>Закрыть</button>
+                </div>
+            </BottomSheetsUi>
+        </div>
+    );
+};
+
+export default App;
+```
+
+## Описание логики
+
+- **Закрытие Bottom Sheet**:
+  - При свайпе вниз (по `touchMove` или `mouseMove`).
+  - При переданном `onHide`, который вызывается с задержкой `200ms`.
+  - При изменении `visible` в `false`.
+
+- **Анимация скрытия**:
+  - Класс `hide` применяется к `bottom-sheets`, плавно скрывая его.
+

package/docs/Button.md

@@ -0,0 +1,48 @@
+
+
+# Button  
+
+`Button` — это универсальный компонент кнопки с поддержкой различных стилей.  
+
+## Внешний вид  
+
+![Botton](img/Button.png)
+
+## Свойства  
+
+| Свойство     | Тип                               | Описание  |
+|-------------|----------------------------------|------------------------------------------------------------------------------------------------|
+| `styleType` | `"outline" \| "text" \| "filledTotal" \| "filled" \| "base"` (необяз.) | Определяет стиль кнопки. По умолчанию `"base"`. |
+| `...props`  | `React.ButtonHTMLAttributes<HTMLButtonElement>` | Любые стандартные свойства кнопки (`onClick`, `disabled`, `className` и т. д.). |
+
+## Использование  
+
+```tsx
+import { Button } from "./Button";
+
+const App = () => (
+    <div>
+        <Button onClick={() => alert("Нажата базовая кнопка")}>Базовая</Button>
+        <Button styleType="outline">Обводка</Button>
+        <Button styleType="text">Текст</Button>
+        <Button styleType="filledTotal">Заливка (Total)</Button>
+        <Button styleType="filled">Заливка</Button>
+    </div>
+);
+
+export default App;
+```
+
+## Описание логики  
+
+- **Ripple-эффект:** При клике создается эффект волны (`btn-overlay`).  
+- **Различные стили кнопки:**  
+  - `"base"` — стандартная кнопка.  
+  - `"outline"` — с обводкой.  
+  - `"text"` — текстовая кнопка без фона.  
+  - `"filledTotal"` — залитая кнопка с другим цветом.  
+  - `"filled"` — залитая кнопка основного цвета.  
+- **Обработчик `onClick`**:  
+  - Добавляет `span.btn-overlay` для эффекта.  
+  - Удаляет его через `500ms`.  
+

package/docs/Card.md

@@ -0,0 +1,130 @@
+# Документация компонента Card
+
+## Обзор
+
+Компонент `Card` представляет собой универсальную карточку с поддержкой различных вариантов отображения контента, состояний и взаимодействий.
+
+## Внешний вид  
+
+![Card](img/Card.png)
+
+## Пропсы
+
+| Пропс            | Тип                     | По умолчанию  | Описание |
+|------------------|-------------------------|---------------|----------|
+| `action`        | `React.ReactNode`       | -             | Элементы действий (кнопки и т.д.) |
+| `imgSrc`        | `string`                | -             | URL изображения |
+| `alt`           | `string`                | -             | Альтернативный текст изображения |
+| `header`        | `string`                | -             | Основной заголовок |
+| `subhead`       | `string`                | -             | Подзаголовок |
+| `text`          | `string`                | -             | Основной текст |
+| `children`      | `React.ReactNode`       | -             | Дочерние элементы |
+| `iconButtonCell`| `React.ReactNode`       | -             | Иконка/кнопка в заголовке |
+| `variant`       | `'elevated'`, `'filled'`, `'outlined'` | `'elevated'` | Вариант стиля |
+| `loading`       | `boolean`               | `false`       | Состояние загрузки |
+| `screenSize`    | `ScreenSize`            | -             | Размер экрана для адаптации |
+| `rootApp`       | `string`                | `'#root'`     | CSS-селектор корневого элемента |
+| `className`     | `string`                | -             | Дополнительные классы |
+| `onClick`       | `(e: React.MouseEvent<HTMLDivElement>) => void` | - | Обработчик клика |
+
+## Примеры использования
+
+### Базовая карточка
+
+```jsx
+<Card 
+  header="Заголовок"
+  text="Основное содержимое карточки"
+/>
+```
+
+### Карточка с изображением
+
+```jsx
+<Card
+  imgSrc="/path/to/image.jpg"
+  alt="Описание изображения"
+  header="Заголовок"
+  subhead="Подзаголовок"
+  text="Текст карточки"
+  variant="elevated"
+/>
+```
+
+### Карточка с действиями
+
+```jsx
+<Card
+  header="Карточка с действиями"
+  text="Выберите действие:"
+  action={
+    <>
+      <Button variant="text">Отмена</Button>
+      <Button>Подтвердить</Button>
+    </>
+  }
+/>
+```
+
+### Карточка в состоянии загрузки
+
+```jsx
+<Card
+  header="Загрузка данных"
+  loading={true}
+/>
+```
+
+### Кастомная карточка
+
+```jsx
+<Card variant="outlined">
+  <CustomChart />
+  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+    <Typography type="body">Статистика</Typography>
+    <Button icon="refresh" variant="icon" />
+  </div>
+</Card>
+```
+
+## Варианты стилей
+
+Компонент поддерживает три визуальных варианта:
+
+1. **Elevated** (по умолчанию) - с тенью
+   ```jsx
+   <Card variant="elevated" />
+   ```
+
+2. **Filled** - с заполненным фоном
+   ```jsx
+   <Card variant="filled" />
+   ```
+
+3. **Outlined** - с границей
+   ```jsx
+   <Card variant="outlined" />
+   ```
+
+## Состояние загрузки
+
+При установке пропса `loading={true}` карточка отображает индикатор загрузки:
+
+```jsx
+<Card loading={true} header="Загрузка..." />
+```
+
+## Особенности работы
+
+1. **Ripple-эффект**: При клике на карточку появляется анимация волны.
+2. **Адаптивность**: Автоматически адаптируется к разным размерам экрана.
+3. **Оптимизация**: Изображения загружаются с атрибутом `loading="lazy"`.
+4. **Доступность**: Поддерживает правильную семантику и ARIA-атрибуты.
+
+## Рекомендации
+
+1. Всегда указывайте `alt` текст для изображений
+2. Для групп карточек используйте одинаковый `variant`
+3. Сочетайте с компонентом `Typography` для единообразия текстов
+4. Используйте состояние `loading` при асинхронной загрузке данных
+5. Кастомизируйте через CSS-переменные для сохранения дизайн-системы

package/docs/Checkbox.md

@@ -0,0 +1,65 @@
+Вот документация для компонента `Checkbox`. Сохрани её в `Checkbox.md`:
+
+---
+
+# Checkbox
+
+`Checkbox` — это компонент для отображения чекбокса с поддержкой кастомных иконок, размеров и состояния.
+
+## Внешний вид  
+
+![Checkbox](img/Checkbox.png)
+
+## Свойства
+
+| Свойство        | Тип                                   | Описание                                                                                           |
+|-----------------|---------------------------------------|---------------------------------------------------------------------------------------------------|
+| `checkIcon`     | `React.ReactNode` (необяз.)           | Кастомная иконка для отмеченного состояния (по умолчанию используется стандартная иконка `Check`). |
+| `size`          | `'small' | 'medium' | 'large'` (необяз.) | Размер чекбокса. По умолчанию `'medium'`.                                                         |
+| `name`          | `string` (необяз.)                    | Имя чекбокса, которое будет использоваться для передачи значения при отправке формы.              |
+| `checked`       | `boolean` (необяз.)                   | Определяет, отмечен ли чекбокс.                                                                   |
+| `onChange`      | `(e: React.ChangeEvent<HTMLInputElement>) => void` (необяз.) | Колбэк, вызываемый при изменении состояния чекбокса.                                               |
+| `readOnly`      | `boolean` (необяз.)                   | Если `true`, чекбокс не может быть изменен.                                                       |
+| `disabled`      | `boolean` (необяз.)                   | Если `true`, чекбокс будет заблокирован.                                                          |
+| `className`     | `string` (необяз.)                    | Дополнительные классы для кастомизации стилей.                                                    |
+
+## Использование
+
+```tsx
+import { Checkbox } from "./Checkbox";
+
+const App = () => {
+  const [checked, setChecked] = useState(false);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setChecked(e.target.checked);
+  };
+
+  return (
+    <div>
+      <Checkbox
+        checked={checked}
+        onChange={handleChange}
+        size="large"
+        checkIcon={<CustomCheckIcon />}
+      />
+    </div>
+  );
+};
+```
+
+## Описание логики
+
+- **Кастомная иконка:** Вы можете передать свою иконку для отмеченного состояния через свойство `checkIcon`.
+- **Размер:** Чекбокс поддерживает 3 размера: `small`, `medium` и `large` (по умолчанию `medium`).
+- **Состояние:** Чекбокс может быть в одном из следующих состояний:
+  - Отмечен (с помощью свойства `checked`).
+  - Заблокирован (с помощью свойства `disabled`).
+  - Только для чтения (с помощью свойства `readOnly`).
+
+
+## Примечания
+
+- Чекбокс использует `React.forwardRef` для передачи ссылки на элемент `input`, что позволяет работать с ним в родительских компонентах.
+- Чекбокс поддерживает кастомные иконки для состояния "отмечено", и это поведение можно легко заменить.
+

package/docs/Chip.md

@@ -0,0 +1,54 @@
+
+# Chips
+
+`Chips` — это компонент для отображения чипсов (вкладок), с возможностью клика и удаления. Чипсы могут быть разных размеров и адаптироваться к различным экранам.
+
+## Внешний вид  
+
+![Chips](img/Chip.png)
+
+## Свойства
+
+| Свойство        | Тип                                     | Описание                                                                                           |
+|-----------------|-----------------------------------------|---------------------------------------------------------------------------------------------------|
+| `text`          | `string`                                | Текст, который будет отображаться внутри чипса.                                                    |
+| `onClick`       | `(e: React.MouseEvent<HTMLDivElement>) => void` (необяз.) | Обработчик клика по чипсу.                                                                         |
+| `onDelete`      | `(e: React.MouseEvent<HTMLButtonElement>) => void` (необяз.) | Обработчик удаления чипса (появляется только если передан).                                         |
+| `big`           | `boolean` (необяз.)                     | Если `true`, чипс будет большого размера.                                                         |
+| `screenSize`    | `ScreenSize` (необяз.)                  | Размер экрана для адаптивного отображения (например, для мобильных устройств).                    |
+| `className`     | `string` (необяз.)                      | Дополнительные классы для кастомизации стилей.                                                    |
+
+## Использование
+
+```tsx
+import { Chips } from "./Chips";
+
+const App = () => {
+  const handleChipClick = () => {
+    console.log("Chip clicked");
+  };
+
+  const handleDelete = () => {
+    console.log("Chip deleted");
+  };
+
+  return (
+    <div>
+      <Chips
+        text="Example Chip"
+        onClick={handleChipClick}
+        onDelete={handleDelete}
+        big
+      />
+    </div>
+  );
+};
+```
+
+## Описание логики
+
+- **Удаление чипса:** Когда чипс имеет обработчик `onDelete`, появляется кнопка для удаления. Клик по кнопке вызовет переданный колбэк.
+- **Клик по чипсу:** Если передан `onClick`, чипс можно кликать. Он будет вести себя как кнопка и использовать роль `button` для доступности.
+- **Размер чипса:** Чипсы поддерживают два размера: маленький и большой. Если передано свойство `big`, чипс будет отображаться в увеличенном размере.
+- **Адаптивность:** Чипсы поддерживают изменение внешнего вида в зависимости от размера экрана, используя свойство `screenSize`.
+

package/docs/ColorField.md

@@ -0,0 +1,89 @@
+# Документация компонента ColorField
+
+## Обзор
+
+Компонент `ColorField` представляет собой поле выбора цвета, которое позволяет пользователям:
+- Просматривать текущий цвет
+- Открывать диалоговое окно выбора цвета
+- Выбирать из предустановленных цветов
+- Добавлять новые цвета в свою палитру
+
+## Внешний вид  
+
+![ColorField](img/ColorField.png)
+
+## Пропсы
+
+| Пропс | Тип | По умолчанию | Описание |
+|-------|-----|--------------|----------|
+| `value` | `string` | `"#f00"` | Текущее значение цвета в HEX-формате |
+| `onChange` | `(value: string) => void` | - | Колбек при изменении цвета |
+| `border` | `boolean` | `false` | Отображать рамку вокруг поля |
+| `className` | `string` | `""` | Дополнительные CSS-классы |
+| `container` | `HTMLElement \| null` | - | DOM-элемент для портала пикера цветов |
+| `transparent` | `boolean` | `false` | Прозрачный фон поля |
+| `placeholder` | `string` | - | Текст-заполнитель при отсутствии цвета |
+| `userColors` | `string[]` | `[]` | Массив пользовательских цветов |
+| `onAddColor` | `(colors: string[]) => void` | - | Колбек при добавлении нового цвета |
+| `defaultColor` | `string` | - | Цвет по умолчанию в пикере |
+
+## Примеры использования
+
+### Базовое использование
+
+```jsx
+<ColorField 
+  value="#3a86ff" 
+  onChange={(color) => console.log(color)} 
+  placeholder="Выберите цвет"
+/>
+```
+
+### С рамкой и пользовательской палитрой
+
+```jsx
+<ColorField
+  border
+  userColors={['#ff0000', '#00ff00', '#0000ff']}
+  onAddColor={(colors) => saveColors(colors)}
+/>
+```
+
+### С прозрачным фоном
+
+```jsx
+<ColorField
+  transparent
+  value="#ffffff"
+  onChange={handleColorChange}
+/>
+```
+
+## Поведение
+
+1. **Отображение цвета**:
+   - Показывает текущий цвет в виде кружка
+   - Отображает HEX-значение рядом
+
+2. **Пикер цвета**:
+   - Открывается по клику на любое место поля
+   - Использует портал для рендеринга вне текущей иерархии DOM
+   - Включает палитру пользовательских цветов (если предоставлена)
+
+3. **Пользовательские цвета**:
+   - При наличии `userColors` показывает их для быстрого выбора
+   - При наличии `onAddColor` позволяет сохранять новые цвета
+
+## Доступность
+
+- Кружок цвета имеет `aria-label="Current color"`
+- Иконка палитры имеет `aria-label="Open color picker"`
+- Цвет текста автоматически контрастирует через хелпер `getTextColor`
+
+## Рекомендации
+
+1. **Указывайте цвет по умолчанию** для необязательных полей
+2. **Используйте пропс container** для правильного позиционирования в модальных окнах
+3. **Реализуйте onAddColor** для сохранения пользовательских цветов
+4. **Добавляйте placeholder** для лучшего UX
+5. **Учитывайте доступность** при выборе цветов по умолчанию