# FileAttach Component

## Описание

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

## Пропсы

| Название            | Тип                                          | По умолчанию          | Описание                                         |
| ------------------- | -------------------------------------------- | --------------------- | ------------------------------------------------ |
| `id`                | `string`                                     | `crypto.randomUUID()` | Уникальный идентификатор компонента              |
| `wrapperClass`      | `string`                                     | `""`                  | Дополнительные CSS-классы для обертки компонента |
| `label`             | `object`                                     | `-`                   | Настройки заголовка компонента                   |
| `label.name`        | `string`                                     | `""`                  | Текст заголовка компонента                       |
| `label.class`       | `string`                                     | `""`                  | CSS-классы для стилизации текста заголовка       |
| `type`              | `"file" \| "image"`                          | `"file"`              | Тип компонента (файл или изображение)            |
| `accept`            | `string`                                     | `"*/*"`               | MIME-типы файлов, которые можно выбрать          |
| `imageSize`         | `object`                                     | `-`                   | Настройки отображения изображения                |
| `imageSize.height`  | `string`                                     | `"10rem"`             | Высота области отображения изображения           |
| `imageSize.width`   | `string`                                     | `"10rem"`             | Ширина области отображения изображения           |
| `imageSize.fitMode` | `"cover" \| "contain"`                       | `"cover"`             | Режим масштабирования изображения                |
| `imageSize.form`    | `"square" \| "circle"`                       | `"square"`            | Форма области отображения изображения            |
| `disabled`          | `boolean`                                    | `false`               | Состояние отключения компонента                  |
| `currentImage`      | `string \| null`                             | `""`                  | Текущее изображение (для связывания)             |
| `onChange`          | `(event: Event, file: File \| null) => void` | `() => {}`            | Обработчик изменения файла                       |

## События

| Название | Тип                                        | Описание                                                                                    |
| -------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| onChange | (event: Event, file: File \| null) => void | Срабатывает при выборе файла, передает событие и выбранный файл (или null если файл удален) |

## Примеры

### Выбор обычного файла

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

  const handleFileChange = (event, file) => {
    if (file) {
      console.log("Выбран файл:", file.name)
    } else {
      console.log("Файл удален")
    }
  }
</script>

<UI.FileAttach id={crypto.randomUUID()} label={{ name: "Выберите файл" }} type="file" onChange={handleFileChange} />
```

### Выбор изображения с предварительным просмотром

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

  let currentImage = ""

  const handleFileChange = (event, file) => {
    if (file) {
      console.log("Выбрано изображение:", file.name)
    } else {
      console.log("Изображение удалено")
    }
  }
</script>

<UI.FileAttach
  id={crypto.randomUUID()}
  label={{ name: "Выберите изображение" }}
  type="image"
  imageSize={{ height: "10rem", width: "10rem", fitMode: "contain" }}
  bind:currentImage
  onChange={handleFileChange}
/>
```

### Отключенный компонент

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

<UI.FileAttach
  id={crypto.randomUUID()}
  label={{ name: "Выберите изображение" }}
  type="image"
  disabled={true}
  imageSize={{ height: "10rem", width: "10rem", fitMode: "cover" }}
/>
```

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

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

- Переменная `selectedFile` хранит выбранный файл
- Переменная `previewUrl` вычисляет URL для предварительного просмотра изображения
- Переменная `fileName` хранит имя выбранного файла
- Объект `ID` генерирует уникальный идентификатор для элемента ввода

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

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

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

- `bind:currentImage` для двусторонней привязки текущего изображения
- Обработчик `onchange` для отслеживания изменения файла
- Обработчик `onclick` для активации выбора файла

### Слоты

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

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

### Описание

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

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

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

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

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

## Заметки

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

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

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

- При работе с изображениями компонент автоматически создает URL предварительного просмотра
- Принимаемые MIME-типы определяются строкой `accept`, которая должна соответствовать спецификации HTML
- Для изображений поддерживается только предварительный просмотр, сохранение происходит через обработчик

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

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