# Button Component

## Описание

Кнопка - это интерактивный UI-компонент, который предоставляет возможность выполнения действий при клике. Компонент поддерживает настройку внешнего вида, иконок, информационных подсказок, горячих клавиш и другие параметры через систему пропсов.

## Пропсы

| Название            | Тип                                                    | По умолчанию          | Описание                                                                                                                                        |
| ------------------- | ------------------------------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | `string`                                               | `crypto.randomUUID()` | Уникальный идентификатор компонента                                                                                                             |
| `wrapperClass`      | `string`                                               | `""`                  | Дополнительные CSS-классы для обертки компонента                                                                                                |
| `componentClass`    | `string`                                               | `""`                  | CSS-классы для стилизации самой кнопки                                                                                                          |
| `disabled`          | `boolean`                                              | `false`               | Состояние отключения кнопки                                                                                                                     |
| `content`           | `object`                                               | `undefined`           | Настройки содержимого кнопки                                                                                                                    |
| `content.name`      | `string`                                               | `""`                  | Текст кнопки                                                                                                                                    |
| `content.info`      | `object`                                               | `undefined`           | Информационная подсказка                                                                                                                        |
| `content.info.text` | `string`                                               | `""`                  | Текст информационной подсказки                                                                                                                  |
| `content.info.side` | `"top" \| "bottom" \| "left" \| "right"`               | `"top"`               | Сторона отображения подсказки                                                                                                                   |
| `content.icon`      | `ConstructorOfATypedSvelteComponent \| string \| null` | `null`                | Иконка, отображаемая в кнопке (SVG строка или Svelte-компонент); без `content.name` и с заданной иконкой кнопка рендерится как круглая без фона |
| `keyBind`           | `object`                                               | `{ showHint: true }`  | Настройки горячих клавиш для активации кнопки                                                                                                   |
| `keyBind.key`       | `string`                                               | `undefined`           | Клавиша для активации                                                                                                                           |
| `keyBind.ctrlKey`   | `boolean`                                              | `undefined`           | Требование нажатия Ctrl                                                                                                                         |
| `keyBind.shiftKey`  | `boolean`                                              | `undefined`           | Требование нажатия Shift                                                                                                                        |
| `keyBind.altKey`    | `boolean`                                              | `undefined`           | Требование нажатия Alt                                                                                                                          |
| `keyBind.metaKey`   | `boolean`                                              | `undefined`           | Требование нажатия Meta (Cmd на Mac)                                                                                                            |
| `keyBind.showHint`  | `boolean`                                              | `true`                | Показывать ли подсказку о горячих клавишах                                                                                                      |
| `onClick`           | `() => void`                                           | `undefined`           | Обработчик клика по кнопке                                                                                                                      |

## События

| Название | Тип        | Описание                                                                |
| -------- | ---------- | ----------------------------------------------------------------------- |
| onClick  | () => void | Срабатывает при клике по кнопке или при активации через горячую клавишу |

## Примеры

### Базовое использование

```svelte
<script>
  import * as UI from "poe-svelte-ui-lib"

  const handleClick = () => {
    console.log("Кнопка нажата!")
  }
</script>

<UI.Button content={{ name: "Button 1" }} componentClass="bg-red" onClick={handleClick} />
```

### Кнопка с информацией и иконкой

```svelte
<script>
  import * as UI from "poe-svelte-ui-lib"
  import IconGripVerticalDual from "./appIcons/IconGripVerticalDual.svelte"

  const handleClick = () => {
    console.log("Кнопка с иконкой нажата!")
  }
</script>

<UI.Button
  content={{
    name: "Button 2",
    icon: IconGripVerticalDual,
    info: { text: "Info for Icon Button", side: "right" },
  }}
  componentClass="bg-green h-12 rounded-3xl"
  onClick={handleClick}
/>
```

### Отключенная кнопка

```svelte
<script>
  import * as UI from "poe-svelte-ui-lib"
</script>

<UI.Button content={{ name: "Button 3" }} componentClass="bg-blue" disabled={true} />
```

### Кнопка только с иконкой

```svelte
<script>
  import * as UI from "poe-svelte-ui-lib"
  import IconGripHorizontalUp from "./appIcons/IconGripHorizontalUp.svelte"

  const handleClick = () => {
    console.log("Кнопка с иконкой нажата!")
  }
</script>

<div class="flex h-10 items-center justify-around">
  <UI.Button content={{ icon: IconGripHorizontalUp }} wrapperClass="w-20 h-10" componentClass="bg-purple rounded-full" onClick={handleClick} />
</div>
```

## Внутренняя архитектура

### Реактивность

- Переменная `showInfo` управляет видимостью информационной подсказки
- Переменная `svgSize` вычисляет размеры SVG иконки на основе классов
- Объект `tooltipConfig` содержит конфигурацию позиционирования подсказок

### Сторы и зависимости

- Используется стор `twMerge` для объединения Tailwind CSS классов
- Применяется переход `fly` из `svelte/transition` для анимации подсказки
- Используется `onMount` для подписки и отписки от глобальных событий клавиатуры

### Директивы

- `transition:fly` для анимации появления/скрытия информационной подсказки
- Обработчики `onmouseenter` и `onmouseleave` для показа/скрытия подсказки
- Обработчик `onclick` для активации кнопки

### Слоты

- Компонент не использует внешних слотов

## Конструктор свойств (ButtonProps.svelte)

### Описание

Компонент `ButtonProps.svelte` предоставляет визуальный интерфейс для редактирования свойств кнопки. Поддерживает два режима отображения: для конструктора и для редактирования.

### Пропсы конструктора

| Название           | Тип                                                                                                                                 | По умолчанию | Описание                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
| `component`        | `UIComponent & { properties: Partial<IButtonProps> }`                                                                               | `-`          | Объект компонента с его свойствами                      |
| `onPropertyChange` | `(updates: Partial<{ properties?: string \| object; name?: string; access?: string; eventHandler?: IUIComponentHandler }>) => void` | `-`          | Коллбэк для обновления свойств компонента               |
| `forConstructor`   | `boolean`                                                                                                                           | `true`       | Режим отображения (для конструктора или редактирования) |

### Особенности конструктора

- Предоставляет визуальные элементы управления для всех доступных свойств
- Включает модальное окно для выбора иконок из библиотеки
- Поддерживает настройку обработчика событий и аргументов
- Имеет различные наборы полей в зависимости от режима (`forConstructor`)
- Использует систему локализации через `$T('constructor.props.*')`
- Поддерживает валидацию вводимых данных через регулярные выражения

## Заметки

### Адаптивность

- Компонент использует Tailwind CSS для адаптивного дизайна
- Используются относительные единицы измерения для обеспечения масштабируемости
- Подсказки автоматически позиционируются в зависимости от стороны отображения

### Ограничения

- При использовании только иконки (без текста) кнопка становится прозрачной без фона
- Горячие клавиши регистрируются глобально и могут конфликтовать с другими компонентами
- Подсказки не поддерживают HTML-разметку, отображают только текст

### Производительность

- Компонент использует оптимизации Svelte для минимизации перерисовок
- Обработчики клавиатуры удаляются при размонтировании компонента
- Используется эффективное объединение классов через `twMerge`