# Switch Component

## Описание

Переключатель - это UI-компонент, который позволяет пользователю управлять булевым значением или битовым значением. Компонент поддерживает различные типы отображения: горизонтальный, вертикальный и чекбокс, а также настройки режима битов, подписей и другие параметры через систему пропсов.

## Пропсы

| Название             | Тип                                        | По умолчанию          | Описание                                                                                                                                                                               |
| -------------------- | ------------------------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | `string`                                   | `crypto.randomUUID()` | Уникальный идентификатор компонента                                                                                                                                                    |
| `height`             | `string`                                   | `"2rem"`              | Высота переключателя: определяет размеры трека и ползунка; ширина в режиме `horizontal` рассчитывается как `height * 2`                                                                |
| `wrapperClass`       | `string`                                   | `""`                  | Дополнительные CSS-классы для обертки компонента                                                                                                                                       |
| `disabled`           | `boolean`                                  | `false`               | Состояние отключения компонента                                                                                                                                                        |
| `label`              | `object`                                   | `-`                   | Настройки заголовка и подписей компонента                                                                                                                                              |
| `label.name`         | `string`                                   | `""`                  | Текст заголовка компонента                                                                                                                                                             |
| `label.class`        | `string`                                   | `""`                  | CSS-классы для стилизации текста заголовка                                                                                                                                             |
| `label.captionLeft`  | `string`                                   | `""`                  | Левая подпись для горизонтального типа (кликабельна, устанавливает значение 0 без `bitMode`)                                                                                           |
| `label.captionRight` | `string`                                   | `""`                  | Правая подпись для горизонтального типа (кликабельна, устанавливает значение 1 без `bitMode`)                                                                                          |
| `hiddenInfo`         | `string`                                   | `""`                  | Текст всплывающей подсказки для режима `checkbox`: отображается при наведении на чекбокс                                                                                               |
| `options`            | `IOption<number>[]`                        | `[]`                  | Массив опций для переключателя                                                                                                                                                         |
| `bitMode`            | `boolean`                                  | `false`               | Режим битовых флагов: при `true` значение интерпретируется как битовая маска, каждая опция управляет отдельным битом через побитовые операции; при `false` — простой переключатель 0/1 |
| `type`               | `"horizontal" \| "vertical" \| "checkbox"` | `"horizontal"`        | Тип отображения: `horizontal` — горизонтальный слайдер, `vertical` — вертикальный слайдер, `checkbox` — стандартный чекбокс с галочкой и поддержкой `hiddenInfo`                       |
| `value`              | `number`                                   | `undefined`           | Текущее значение переключателя: в обычном режиме — 0 или 1, в `bitMode` — битовая маска; поддерживает двустороннее связывание (`$bindable`)                                            |
| `onChange`           | `(value: number) => void`                  | `() => {}`            | Обработчик изменения значения                                                                                                                                                          |

### Вложенные типы

#### IOption

| Название   | Тип       | По умолчанию | Описание                                          |
| ---------- | --------- | ------------ | ------------------------------------------------- |
| `id`       | `string`  | `-`          | Уникальный идентификатор опции                    |
| `value`    | `number`  | `undefined`  | Значение опции (номер бита или значение)          |
| `name`     | `string`  | `undefined`  | Отображаемое имя опции (используется в `bitMode`) |
| `class`    | `string`  | `undefined`  | CSS-классы для стилизации опции                   |
| `disabled` | `boolean` | `undefined`  | Состояние отключения опции                        |

## События

| Название | Тип                     | Описание                                         |
| -------- | ----------------------- | ------------------------------------------------ |
| onChange | (value: number) => void | Срабатывает при изменении значения переключателя |

## Примеры

### Горизонтальный переключатель

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

  let switchValue = 0

  const handleChange = (value) => {
    switchValue = value
    console.log("Новое значение:", value)
  }
</script>

<UI.Switch
  wrapperClass="w-1/3"
  label={{ name: "Переключатель 1", captionLeft: "Off", captionRight: "On" }}
  bind:value={switchValue}
  options={[{ id: crypto.randomUUID(), value: 0, class: "bg-blue" }]}
  onChange={handleChange}
/>
```

### Вертикальный переключатель

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

  let switchValue = 0

  const handleChange = (value) => {
    switchValue = value
    console.log("Новое значение:", value)
  }
</script>

<UI.Switch
  wrapperClass="w-1/3"
  label={{ name: "Переключатель 2" }}
  type="vertical"
  bind:value={switchValue}
  options={[{ id: crypto.randomUUID(), value: 0, class: "bg-red" }]}
  onChange={handleChange}
/>
```

### Чекбокс

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

  let switchValue = 0

  const handleChange = (value) => {
    switchValue = value
    console.log("Новое значение:", value)
  }
</script>

<UI.Switch
  wrapperClass="bg-yellow w-1/3"
  label={{ name: "Галочка" }}
  type="checkbox"
  bind:value={switchValue}
  options={[{ id: crypto.randomUUID(), value: 0, class: "" }]}
  onChange={handleChange}
/>
```

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

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

- Переменная `checkedOptions` вычисляет состояние каждого бита в режиме bitMode
- Переменная `localOptions` фильтрует опции в зависимости от режима работы
- Функция `handleToggle` переключает состояние бита или значения переключателя
- Функция `handleCaptionClick` обрабатывает клики по подписям для горизонтального типа

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

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

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

- `bind:value` для двусторонней привязки значения
- `transition:fly` для анимации информационной подсказки
- `$effect` для инициализации значения при его отсутствии

### Слоты

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

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

### Описание

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

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

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

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

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

## Заметки

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

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

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

- В режиме bitMode поддерживается до 32 битов
- Для типа "checkbox" не доступны подписи captionLeft и captionRight
- При использовании режима bitMode недоступен тип "checkbox"

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

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