[web-animations-2] Propose syntax of imperative API for animation-trigger

[ydaniv]

This is a followup on #8942, looking a bit ahead and proposing an imperative syntax for animation-trigger in Web Animation API.

The main idea is to introduce a new class AnimationTrigger that takes an options object, as below:

interface AnimationTrigger {
  constructor(AnimationTriggerOptions options)
  attribute AnimationTimeline timeline;
  attribute AnimationTriggerType type;
  attribute TimelineRangeOffset rangeStart;
  attribute TimelineRangeOffset rangeEnd;
  attribute TimelineRangeOffset exitRangeStart;
  attribute TimelineRangeOffset exitRangeEnd;
}

dictionary AnimationTriggerOptions {
  AnimationTimeline? timeline = DocumentTimeline
  AnimationTriggerType? type = "once"
  TimelineRangeOffset? rangeStart = "normal"
  TimelineRangeOffset? rangeEnd
  TimelineRangeOffset? exitRangeStart
  TimelineRangeOffset? exitRangeEnd
}

enum AnimationTriggerType = { "once", "repeat", "alternate", "state" }

And the the following example in CSS:

#target {
  animation-trigger: repeat view() contain cover;
}

becomes this in JS:

const view = new ViewTimeline({
  subject: '#target'
});

const trigger = new AnimationTrigger({
  type: 'repeat',
  timeline: view,
  rangeStart: 'contain 0%',
  rangeEnd: 'contain 100%',
  exitRangeStart: 'cover 0%',
  exitRangeEnd: 'cover 100%'
});

The four properties for range seem a bit overwhelming, but this should follow current syntax for rangeStart/End for scroll-driven animations. Perhaps it's worth to consider only 2 properties like: range and exitRange that will take the shorthand form?

Then, usage with Animation could be:

const effect = new KeyframeEffect(target, {
  opacity: [0, 1]
});

const animation = new Animation(effect, {
  trigger: trigger
});

Notice I overloaded the Animation constructor's signature with a property bag as a second parameter, instead of an AnimationTimeline. The idea is that, if possible, we could overload it to accept either a timeline, or a dict with optional properties, currently timeline and trigger.

Or, alternatively, via .animate():

target.animate({ opacity: [0, 1] }, {
  duration: 1000,
  easing: 'ease-in',
  trigger: trigger
});

cc: @flackr @birtles