# Joystick Component

## Описание

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

## Пропсы

| Название        | Тип                                                    | По умолчанию          | Описание                                                                                                                                                                                        |
| --------------- | ------------------------------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | `string`                                               | `crypto.randomUUID()` | Уникальный идентификатор компонента                                                                                                                                                             |
| `wrapperClass`  | `string`                                               | `""`                  | Дополнительные CSS-классы для обертки компонента                                                                                                                                                |
| `label`         | `object`                                               | `-`                   | Настройки заголовка компонента                                                                                                                                                                  |
| `label.name`    | `string`                                               | `""`                  | Текст заголовка компонента                                                                                                                                                                      |
| `label.class`   | `string`                                               | `""`                  | CSS-классы для стилизации текста заголовка                                                                                                                                                      |
| `value`         | `number[]`                                             | `[0, 0, 0, 0]`        | Значения осей джойстика (`pitch`, `yaw`, `roll` — в зависимости от заданных осей) и, последним элементом, флаг состояния центральной кнопки; поддерживает двустороннее связывание (`$bindable`) |
| `readonly`      | `boolean`                                              | `false`               | Режим только для чтения (без возможности управления)                                                                                                                                            |
| `axes`          | `{ name: string; minNum?: number; maxNum?: number }[]` | `-`                   | Определение осей управления (2 или 3 элемента, по умолчанию — Pitch/Yaw/Roll); пустое `name` у третьей оси скрывает боковые кнопки управления `roll`                                            |
| `axes[].name`   | `string`                                               | `-`                   | Название оси                                                                                                                                                                                    |
| `axes[].minNum` | `number`                                               | `-360`                | Минимальное значение оси                                                                                                                                                                        |
| `axes[].maxNum` | `number`                                               | `360`                 | Максимальное значение оси                                                                                                                                                                       |
| `buttonIcon`    | `ConstructorOfATypedSvelteComponent \| string`         | `undefined`           | Иконка для центральной кнопки                                                                                                                                                                   |
| `onUpdate`      | `(value: number[]) => void`                            | `() => {}`            | Обработчик изменения значения осей                                                                                                                                                              |

## События

| Название | Тип                                | Описание                                          |
| -------- | ---------------------------------- | ------------------------------------------------- |
| onUpdate | ([number, number, number]) => void | Срабатывает при изменении значений осей джойстика |

## Примеры

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

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

<UI.Joystick label={{ name: "Управление по 3 осям" }} />
```

### С настраиваемыми осями

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

  let joystickValue = [0, 0, 0]

  const handleUpdate = (value) => {
    joystickValue = value
    console.log("Новые значения осей:", value)
  }
</script>

<UI.Joystick
  label={{ name: "Управление по 2 осям" }}
  axes={[
    { name: "Pitch", minNum: -100, maxNum: 100 },
    { name: "Yaw", minNum: -100, maxNum: 100 },
  ]}
  buttonIcon={IconGripVerticalDual}
  bind:value={joystickValue}
  {onUpdate}
/>
```

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

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

- Переменная `value` хранит текущие значения осей (для двусторонней привязки)
- Переменная `sensitivity` управляет чувствительностью управления
- Объект `directions` определяет направления и действия для каждой кнопки джойстика
- Функция `updateValue` изменяет значение конкретной оси с учетом ограничений

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

- Используется стор `twMerge` для объединения Tailwind CSS классов
- Используются тригонометрические функции для расчета позиций элементов джойстика

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

- `bind:value` для двусторонней привязки значений осей
- `$effect` для обработки изменений чувствительности и значений
- `onmouseenter` и `onmouseleave` для визуальной обратной связи при наведении

### Слоты

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

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

### Описание

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

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

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

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

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

## Заметки

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

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

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

- Компонент поддерживает до 3 осей управления (Pitch, Roll, Yaw)
- В режиме `readonly` все элементы управления недоступны для взаимодействия
- Центральная кнопка может работать как кнопка возврата в исходное положение или как переключатель

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

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