# ProgressBar Component

## Описание

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

## Пропсы

| Название            | Тип                                   | По умолчанию                     | Описание                                                                                                         |
| ------------------- | ------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `id`                | `string`                              | `crypto.randomUUID()`            | Уникальный идентификатор компонента                                                                              |
| `wrapperClass`      | `string`                              | `""`                             | Дополнительные CSS-классы для обертки компонента                                                                 |
| `items`             | `{ name?: string; class?: string }[]` | `[{ name: "Label", class: "" }]` | Массив элементов индикатора прогресса                                                                            |
| `items[].name`      | `string`                              | `"Label"`                        | Название элемента                                                                                                |
| `items[].class`     | `string`                              | `""`                             | CSS-классы для стилизации элемента                                                                               |
| `value`             | `IReceivingDataObject[]`              | `undefined`                      | Значения индикаторов прогресса — по одному объекту на каждый элемент из `items` (индексы должны соответствовать) |
| `value[].Name`      | `string`                              | `undefined`                      | Имя элемента; при наличии переопределяет `name` из `items` для отображения                                       |
| `value[].Timestamp` | `string`                              | `undefined`                      | Временная метка значения                                                                                         |
| `value[].Value`     | `number \| string \| boolean`         | `undefined`                      | Текущее значение индикатора                                                                                      |
| `value[].Info`      | `string`                              | `undefined`                      | Дополнительная информация, отображаемая под индикатором                                                          |
| `type`              | `"horizontal" \| "vertical"`          | `"horizontal"`                   | Тип ориентации индикатора                                                                                        |
| `number`            | `object`                              | `-`                              | Настройки числовых значений                                                                                      |
| `number.minNum`     | `number`                              | `0`                              | Минимальное значение                                                                                             |
| `number.maxNum`     | `number`                              | `100`                            | Максимальное значение                                                                                            |
| `number.units`      | `string`                              | `"%"`                            | Единицы измерения                                                                                                |

## События

Компонент не генерирует специфические события.

## Примеры

### Горизонтальный индикатор прогресса

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

  let progressBarValue = 40
</script>

<UI.ProgressBar value={progressBarValue} wrapperClass="bg-red" />
```

### Вертикальный индикатор прогресса

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

  let progressBarValue = 65
</script>

<UI.ProgressBar value={progressBarValue} type="vertical" wrapperClass="bg-red h-50" />
```

### С несколькими элементами

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

  let multipleValues = [
    { Name: "CPU", Value: 75, Info: "Загрузка процессора" },
    { Name: "RAM", Value: 50, Info: "Использование памяти" },
    { Name: "DISK", Value: 30, Info: "Загрузка диска" },
  ]

  let items = [
    { name: "CPU", class: "bg-blue" },
    { name: "RAM", class: "bg-green" },
    { name: "DISK", class: "bg-yellow" },
  ]
</script>

<UI.ProgressBar {items} value={multipleValues} number={{ minNum: 0, maxNum: 100, units: "%" }} />
```

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

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

- Переменная `min` и `max` вычисляют минимальное и максимальное значения
- Функция `numericValue` нормализует входящие значения
- Функция `progressPercent` вычисляет процент заполнения индикатора
- Функция `roundToClean` округляет числа для отображения

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

- Используется стор `twMerge` для объединения Tailwind CSS классов

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

- `$derived` для вычисления минимального и максимального значений
- `#each` для отображения нескольких элементов индикатора

### Слоты

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

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

### Описание

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

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

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

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

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

## Заметки

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

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

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

- Значения индикатора ограничены минимальным и максимальным значениями
- Для вертикального типа рекомендуется задавать высоту контейнера
- Множественные индикаторы отображаются в одном контейнере

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

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