Документирование анимационной системы

Документирование анимационной системы в Motion One строится вокруг описания минимального набора примитивов, из которых формируются все анимационные сценарии: ключевые кадры, свойства, тайминг, управление прогрессом и взаимодействие с внешними событиями. Система проектируется как декларативная надстройка над Web Animations API, сохраняя совместимость с браузерной моделью исполнения анимаций и добавляя единый интерфейс управления.

Документация такой системы требует строгого разделения уровней абстракции:

  • уровень описания анимации (declarative layer)
  • уровень исполнения (runtime layer)
  • уровень управления (control layer)
  • уровень композиции (timeline layer)

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

Базовая модель анимации

В основе системы лежит функция animate, принимающая описание цели, набора свойств и параметров времени. Документирование этой функции опирается на формализацию сигнатуры и семантики аргументов.

animate(
  target: Element | Element[],
  keyframes: Keyframes,
  options?: AnimationOptions
)

Целевой элемент

Целевой объект может быть DOM-узлом или коллекцией узлов. Документация фиксирует следующие особенности:

  • поддержка массива элементов приводит к синхронному созданию экземпляров анимации
  • каждый элемент получает независимый Animation-контроллер
  • возврат функции агрегирует управление через общий интерфейс

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

Ключевые кадры как декларативная структура

Ключевые кадры описываются как объект или массив объектов. Документирование требует строгого описания приоритетов интерполяции.

Объектная форма

{
  opacity: [0, 1],
  transform: ["translateY(20px)", "translateY(0px)"]
}

Массивная форма

[
  { opacity: 0, transform: "translateY(20px)" },
  { opacity: 1, transform: "translateY(0px)" }
]

В документации фиксируются различия:

  • объектная форма интерпретируется как линейная интерполяция значений
  • массивная форма задаёт промежуточные состояния
  • порядок ключей определяет временную ось

Особое внимание уделяется нормализации значений. Система автоматически приводит CSS-значения к интерполируемому виду, включая единицы измерения и цветовые пространства.

Параметры времени и тайминг

Тайминг описывается через набор параметров, определяющих поведение анимации во времени.

Основные поля:

  • duration
  • delay
  • endDelay
  • easing
  • repeat
  • direction

Документирование требует строгого описания взаимодействия этих параметров.

Длительность

duration: number | string

Числовое значение трактуется как миллисекунды. Строковое значение может использоваться в контексте предопределённых профилей.

Задержка

delay определяет смещение начала анимации относительно момента вызова. В документации фиксируется важный аспект: задержка влияет только на стартовую фазу, но не изменяет длительность жизненного цикла экземпляра.

Функции сглаживания (easing)

Easing описывает кривую распределения прогресса анимации.

Поддерживаются следующие типы:

  • cubic-bezier выражения
  • предустановленные строки
  • пользовательские функции

Документирование easing требует формализации входа и выхода функции:

(progress: number) => number

Семантика интерполяции

  • входной диапазон всегда нормализован в [0, 1]
  • выход может выходить за пределы диапазона для эффекта overshoot
  • композиция easing-функций не является коммутативной операцией

Особое внимание уделяется тому, что easing применяется к нормализованному времени, а не к абсолютному таймингу.

Управляющий интерфейс анимации

Результат вызова animate возвращает контроллер, который инкапсулирует состояние анимации.

Основные методы:

  • play
  • pause
  • stop
  • finish
  • reverse

Документирование этих методов фиксирует их влияние на внутреннее состояние:

play

Переводит анимацию в активное состояние. Если прогресс был остановлен, восстановление происходит с сохранённой позиции.

pause

Фиксирует текущее состояние без изменения прогресса. Важно, что временная шкала замораживается, но не пересоздаётся.

stop

Полностью прекращает выполнение и сбрасывает состояние к начальному значению.

Таймлайн как механизм композиции

Таймлайн представляет собой систему синхронизации нескольких анимаций.

Документирование таймлайна включает:

  • порядок добавления анимаций
  • наследование параметров времени
  • управление групповой синхронизацией

Модель исполнения

Каждая анимация получает относительное время старта, вычисляемое относительно базового времени таймлайна.

timeline.add(target, keyframes, options)

Особенность системы заключается в том, что таймлайн не создаёт отдельного потока исполнения — все расчёты происходят в едином цикле обновления.

Интерполяция значений

Система поддерживает интерполяцию различных типов данных:

  • числа
  • строки с единицами измерения
  • цвета
  • трансформации
  • массивы значений

Документирование интерполяции требует указания стратегии преобразования:

Числовые значения

Прямое линейное преобразование:

result = a + (b - a) * t

Строковые значения

Строки парсятся на компоненты, после чего применяется поэлементная интерполяция.

Цвета

Цветовые значения нормализуются в RGBA-пространство перед вычислением промежуточных состояний.

Система spring-анимаций

Spring-модель добавляет физически-ориентированное поведение.

Документация описывает параметры:

  • stiffness
  • damping
  • mass

Математическая модель

Поведение описывается дифференциальным уравнением второго порядка, моделирующим систему пружина–демпфер.

m * x'' + c * x' + k * x = 0

Документирование требует фиксации:

  • начальных условий
  • ограничения устойчивости
  • поведения при переусилении демпфирования

Scroll и событийные привязки

Анимации могут быть связаны с прокруткой страницы.

Документирование scroll-системы включает:

  • привязку прогресса к позиции scrollY
  • нормализацию координат в диапазон 0–1
  • поддержку pinning и offsets

Принцип синхронизации

Scroll становится источником времени, заменяя requestAnimationFrame-цикл. В этом режиме анимация перестаёт быть автономной и становится реактивной относительно внешнего состояния.

Типизация и контракт API

Документирование TypeScript-слоя фиксирует контракт между runtime и пользовательским кодом.

Основные интерфейсы:

  • AnimationOptions
  • Keyframes
  • AnimationControls

Особое внимание уделяется строгой типизации easing-функций и поддержке перегрузок.

type Easing = (t: number) => number

Контракт гарантирует, что любая функция easing должна быть чистой и детерминированной.

Поведение в edge-cases

Документация анимационной системы обязательно фиксирует граничные случаи:

  • нулевая длительность приводит к мгновенному применению конечного состояния
  • отрицательные значения интерпретируются как 0
  • удалённые из DOM элементы приводят к отмене анимации
  • повторные вызовы animate на одном элементе создают независимые экземпляры

Модель обновления и цикл исполнения

Исполнение анимаций основано на цикле обновления, синхронизированном с requestAnimationFrame.

Документирование включает:

  • частоту обновления зависит от дисплея
  • расчёт прогресса основан на timestamp
  • минимизация layout thrashing достигается через batching

Каждый кадр проходит стадии:

  1. вычисление времени
  2. нормализация прогресса
  3. применение easing
  4. интерполяция значений
  5. запись в DOM

Композиция анимаций

Анимации могут комбинироваться через:

  • последовательное выполнение
  • параллельное выполнение
  • вложенные таймлайны

Документирование композиции требует описания приоритетов:

  • локальные параметры перекрывают глобальные таймлайн-настройки
  • конфликты свойств разрешаются по последнему объявлению
  • синхронизация времени происходит через общий reference point

Отладочная модель и трассировка состояния

Документирование включает описание внутренних инструментов диагностики:

  • текущий прогресс анимации
  • вычисленные значения свойств
  • активный easing
  • состояние контроллера

Эта модель используется для воспроизводимости багов и анализа производительности.

Производительность и оптимизация исполнения

Система оптимизирует выполнение через:

  • батчинг обновлений DOM
  • минимизацию перерасчёта layout
  • кэширование интерполяционных функций
  • отказ от лишних пересозданий анимаций

Документирование производительности фиксирует зависимость между количеством одновременно активных анимаций и нагрузкой на main thread.

Совместимость с Web Animations API

Анимационная модель сохраняет совместимость с Web Animations API:

  • контроллеры соответствуют интерфейсу Animation
  • keyframes интерпретируются аналогично WAAPI
  • timing options частично маппятся напрямую

Это позволяет документировать систему как расширение, а не замену базового стандарта браузера.

Оглавление