[scroll-animations-1] JS API for view-timeline-inset

[flackr]

In CSS we have view-timeline-inset to allow reducing the portion of the scroll area which would be considered visible, however the JS ViewTimeline constructor does not have the ability to set the same property.

I propose extending the ViewTimelineOptions dictionary with a property that allows setting the one or two valued inset. The equivalent property in IntersectionObserver is a DOMString rootMargin which is a space separated list of offsets. We could do the same here, but call it inset (to be consistent with the CSS property), or we could accept an array of CSSNumeric values.

Option 1: DOMString

dictionary ViewTimelineOptions {
  Element subject;
  ScrollAxis axis = "block";
  DOMString inset = "0px 0px";
};

Option 2: CSSNumeric

dictionary ViewTimelineOptions {
  Element subject;
  ScrollAxis axis = "block";
  sequence<CSSNumericValue> inset = [CSS.px(0), CSS.px(0)];
};

I think there's a slight advantage to accepting the string syntax in that:

• It allows specifying the auto value from view-timeline-inset, and
• You can pass the computed value of view-timeline-inset, e.g. new ViewTimeline({subject: el, inset: getComputedStyle(subject).viewTimelineInset})

However, passing and parsing a string seems slightly inconsistent with the direction of other JS API's where we've decided to go in the direction of richer types, e.g. #7589.

[fantasai]

Do we want to allow both versions of input? Is that a thing we can do?

[birtles]

Allowing both definitely seems attractive. Should ViewTimeline also expose these values as (readonly?) attributes? Perhaps using the typed version?

[flackr]

Allowing both definitely seems attractive.

Allowing both sounds reasonable to me.

Should ViewTimeline also expose these values as (readonly?) attributes? Perhaps using the typed version?

Yes, I think it should.

[fantasai]

Should the attributes be sequence<CSSNumericValue> inset or CSSNumericValue startInset; CSSNumericValue endInset;? The latter seems a bit more obvious.

[flackr]

Good question, when providing CSSNumericValues the latter seems more obvious, but if we want to accept strings as well I think it's better to have one property so you can pass the computed value string from view-timeline-inset directly without having to split it as in my example above:

new ViewTimeline({
  subject: el,
  inset: getComputedStyle(subject).viewTimelineInset})

Whereas with startInset and endInset as separate properties you'd presumably have to split it like so:

const insets = getComputedStyle(subject).viewTimelineInset.split(' ');
new ViewTimeline({
  subject: el,
  startInset: insets[0],
  endInset: insets[1] || insets[0] /* Use first inset for endInset if no second inset supplied */
});

[fantasai]

@flackr Oh, I didn't mean for the input -- that makes sense to me as-is. But there was a suggestion to add an inset attribute to the ViewTimeline object itself. Which does bring up a few interesting questions:

• should the inset be incorporated into the startOffset / endOffset readouts? Or should those represent raw object bounds only?
• should the inset be a separate attribute? If so, as one sequence attribute inset or as startInset and endInset? (Personally, I think the latter is more understandable, even if the input object uses a sequence.)

My original thought was that startOffset and endOffset would be the effective start/end of the timeline, and incorporate any inset calculations.

[LeaVerou]

Do we want to allow both versions of input? Is that a thing we can do?

Yup, and I think accepting both is the way to go.

[flackr]

@fantasai sorry for the confusion, makes sense!

• should the inset be incorporated into the startOffset / endOffset readouts? Or should those represent raw object bounds only?

I agree with your assessment, that startOffset and endOffset should probably incorporate inset calculations.

• should the inset be a separate attribute? If so, as one sequence attribute inset or as startInset and endInset? (Personally, I think the latter is more understandable, even if the input object uses a sequence.)

I think you could make a similar argument that by exposing insets it makes it more ergonomic to pass one view timeline's insets to another, e.g.

let timeline2 = new ViewTimeline({
  subject: el,
  insets: timeline1.insets
});

This is also similar in spirit to how intersectionObserver exposes the rootMargin with a syntax similar to the inut: https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin

Though I think that's a fairly weak reason to do it and would be fine with it being separated into startInset and endInset since as you say this is more understandable.

[fantasai]

OK, I think we can split this issue down into three sub-points:

Resolution 1: Proposed to accept both string and TypedOM 2-value sequence inset within ViewTimeline Options. @flackr would you mind posting the WebIDL for this? :)

Resolution 2: Proposed that existing ViewTimeline.startOffset and .endOffset attributes incorporate inset calculations (so that they continue to accurately represent the start/end scroll offsets of the ViewTimeline within the scroll container).

Resolution 3: Choose one of

• Add inset two-value sequence to ViewTimeline
• Add startInset and endInset to ViewTimeline
• Don't add inset attributes to ViewTimeline yet, just store them internally

(I'm leaning towards the third.)

[flackr]

Thanks @fantasai, I agree on all three points.

Resolution 1: Proposed to accept both string and TypedOM 2-value sequence inset within ViewTimeline Options. @flackr would you mind posting the WebIDL for this? :)

I think this would be:

dictionary ViewTimelineOptions {
  Element subject;
  ScrollAxis axis = "block";
  DOMString or sequence<CSSNumericValue> inset = [CSS.px(0), CSS.px(0)];
};

(I'm leaning towards the third.)

I'm also leaning towards the third.

[flackr]

@tabatkins I think you had reason to not support string values in these contexts (from #4352 (comment)).

If we do this, it would probably be good to remove support for supplying a string like "42px", that way we can infer that strings are keywords.

[tabatkins]

Yeah, specifically I mean there not parsing a string as a CSS value, instead just letting strings be keyword values. That would imply that "42px" would be the ident with value "42px", written as \34 2px in CSS syntax. While we're not universal with it, we often do this sort of "the string is used literally" behavior precisely so you don't have nested escapes, with a CSS escape put in a JS string and thus needing to be JS-escaped as well. It's also slightly better perf to not invoke the parser unnecessarily.