Миграция с предыдущих версий

Библиотека Unpoly развивается, и каждая новая версия может содержать изменения в API, поведении по умолчанию и способах интеграции с серверной частью. Переход с предыдущих версий требует внимательного подхода, особенно если проект активно использует динамическое обновление контента и кастомные обработчики событий.

Изменения в синтаксисе и API

Unpoly 2.x и выше вводит обновлённые методы для работы с фрагментами страниц и обработкой событий. Основные моменты:

Методы up.replace и up.append В новых версиях строго разделены: up.replace(selector, html, options) заменяет содержимое выбранного элемента, тогда как up.append(selector, html, options) добавляет новый контент. Ранее один метод мог выполнять оба действия в зависимости от переданных аргументов. Важно проверить все вызовы этих функций в проекте и привести их к новой сигнатуре.
Формат опций Опции теперь должны быть переданы объектом с ключами target, animation, focus, history, а не через позиционные аргументы. Это влияет на обработку анимаций и навигации:
```
up.replace('.content', '<p>Обновлено</p>', {
    animation: 'cross-fade',
    focus: true
});
```
Обновление событий События up:fragment:loaded, up:fragment:revealed и up:fragment:removed стали более строгими по контексту. Любая кастомная логика, привязанная к старым событиям, может не сработать, если не указать правильный селектор фрагмента или контекст:
```
up.on('up:fragment:loaded', '.content', (event) => {
    console.log('Фрагмент загружен:', event.target);
});
```

Работа с формами

Unpoly активно использует AJAX для отправки форм. Основные изменения:

Атрибут up-target теперь строго определяет элемент, который будет заменён или обновлён после отправки формы. Если он не указан, по умолчанию обновляется родительский фрагмент формы.
Методы up.submit и up.follow требуют корректного указания опций для управления историей (history: true/false) и анимацией.
Обработка ошибок сервера через события up:form:response и up:form:invalid стала более детализированной, позволяя разделять серверные ошибки и ошибки валидации:
```
up.on('up:form:invalid', '#user-form', (event) => {
    console.log('Ошибка валидации формы:', event.detail.response);
});
```

Навигация и история

В новых версиях улучшена интеграция с history.pushState и popstate. Следует обратить внимание на:

up.history.enabled по умолчанию включен. Для сохранения старого поведения необходимо явно отключить.
Изменился способ обработки переходов по ссылкам с up-follow. Старая логика без указания data-up-target теперь может не работать.
Метод up.navigate требует явного указания целевого фрагмента или документа. Ранее можно было вызывать его без аргументов, опираясь на контекст текущего события.

Миграция кастомных компонентов

Если проект использует пользовательские компоненты или плагины:

Проверить, не используют ли они устаревшие методы up.render, up.insert без объекта опций.
Все внутренние селекторы и события должны быть перепроверены, так как контекст event.target и event.fragment стал более точным.
Для компонентов с динамическим контентом важно использовать делегирование через up.on с указанием селектора, а не прямое присоединение событий к элементам.

Советы по постепенной миграции

Аудит текущих вызовов Unpoly Перечислить все места, где используются up.replace, up.append, up.submit, up.follow, и проверить их сигнатуру.
Тестирование форм и фрагментов Создать отдельный набор тестов для форм и динамических фрагментов. Проверять загрузку, обновление и удаление элементов.
Проверка анимаций и фокуса В новой версии поведение animation и focus может отличаться. Настроить для всех ключевых фрагментов.
История и навигация Убедиться, что переходы через ссылки и кнопки корректно отражаются в window.history.
Обработка событий Проверить, что кастомные события обрабатываются с правильным селектором и контекстом.

Проблемные места при миграции

Старые вызовы up.replace(html) без селектора могут работать некорректно.
Динамически добавленные элементы, на которые назначены события через прямое addEventListener, могут не получать события фрагментов.
Формы с вложенными фрагментами могут некорректно обновляться без явного указания up-target.
Использование устаревших атрибутов вроде data-up-transition требует проверки совместимости с новым синтаксисом animation.