Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[css-animations-2] Specify the animation-trigger property #10128

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

[css-animations-2] Specify the animation-trigger property #10128

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
133f6e0
[css-animations-2] Specify the animation-trigger property
ydaniv Mar 25, 2024
f3a49ba
Fixed syntax of single-animation-trigger + some link fixes
ydaniv Mar 25, 2024
cbd4f07
More fixes to links and defs
ydaniv Mar 27, 2024
9f6464a
More fixes to links and defs
ydaniv Mar 28, 2024
912426a
Move all definitions to web-animations-1;
ydaniv Apr 17, 2024
9ae1a13
Fixed idle state definition for animation trigger state
ydaniv Apr 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
168 changes: 168 additions & 0 deletions css-animations-2/Overview.bs
View file
Open in desktop
Expand Up @@ -68,6 +68,8 @@ spec:web-animations-1; type:dfn;
text:start delay
text:target element
text:unresolved
text:default range
text:exit range
</pre>

<h2 id="delta">Delta specification</h2>
Expand Down Expand Up @@ -690,7 +692,173 @@ The 'animation' shorthand property syntax is as follows:

<span class=prod><dfn>&lt;single-animation></dfn> = <<'animation-duration'>> || <<easing-function>> || <<'animation-delay'>> || <<single-animation-iteration-count>> || <<single-animation-direction>> || <<single-animation-fill-mode>> || <<single-animation-play-state>> || [ none | <<keyframes-name>> ] || <<single-animation-timeline>></span>

<h2 id="animation-triggers">
Declaring Animation Triggers</h2>

Animation Triggers are defined using the 'animation-trigger-*' properties.
These list-valued properties,
which are all [=longhands=] of the 'animation-trigger' [=shorthand=],
form a [=coordinating list property group=]
with 'animation-name' as the [=coordinating list base property=]
and each item in the [=coordinated value list=]
defining the properties of a single animation trigger.

## The 'animation-trigger-type' property ## {#animation-trigger-type}

The 'animation-trigger-type' property specifies the [=animation trigger type=]
of the [=animation trigger=].

<pre class='propdef'>
Name: animation-trigger-type
Value: <<single-animation-trigger-type>>#
Initial: once
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: list, each item a keyword as specified
Animation type: not animatable
Canonical order: per grammar
</pre>

<span class=prod><dfn>&lt;single-animation-trigger-type></dfn> = once | repeat | alternate | state</span>

## The 'animation-trigger-timeline' property ## {#animation-trigger-timeline}

The 'animation-trigger-timeline' property specifies the <a>timeline</a>
of the animation’s associated [=animation trigger=].

<pre class='propdef'>
Name: animation-trigger-timeline
Value: <<single-animation-timeline>>#
Initial: auto
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: list, each item either
the keyword ''single-animation-timeline/none'',
the keyword ''single-animation-timeline/auto'',
a case-sensitive [=css identifier=],
a computed ''scroll()'' function,
or
a computed ''view()'' function
Canonical order: per grammar
Animation Type: not animatable
</pre>

Issue: Probably a trigger with timeline "none" is under-specified here. Need to clarify what it means.

## The 'animation-trigger-range' property ## {#animation-trigger-range}

The 'animation-trigger-range' property is a [=shorthand property|shorthand=]
that sets 'animation-trigger-range-start' and 'animation-trigger-range-end'
together in a single declaration,
specifying the [=animation trigger=]’s associated [=default range=].

<pre class="propdef shorthand">
Name: animation-trigger-range
Value: [ <<'animation-range-start'>> <<'animation-range-end'>>? ]#
</pre>

## The 'animation-trigger-range-start' property ## {#animation-trigger-range-start}

<pre class="propdef">
Name: animation-trigger-range-start
Value: [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: normal
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-range-start/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-range-start' property specifies the start of the [=animation trigger=]’s
associated [=default range=].

## The 'animation-trigger-range-end' property ## {#animation-trigger-range-end}

<pre class="propdef">
Name: animation-trigger-range-end
Value: [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: normal
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-range-end/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-range-end' property specifies the end of the [=animation trigger=]’s
associated [=default range=].

## The 'animation-trigger-exit-range' property ## {#animation-trigger-exit-range}

<pre class="propdef shorthand">
Name: animation-trigger-exit-range
Value: [ <<'animation-trigger-exit-range-start'>> <<'animation-trigger-exit-range-end'>>? ]#
</pre>

The 'animation-trigger-exit-range' property is a [=shorthand property|shorthand=]
that sets 'animation-trigger-exit-range-start' and 'animation-trigger-exit-range-end'
together in a single declaration,
specifying the [=animation trigger=]’s associated [=exit range=].

## The 'animation-trigger-exit-range-start' property ## {#animation-trigger-exit-range-start}

<pre class="propdef">
Name: animation-trigger-exit-range-start
Value: [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: normal
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-exit-range-start/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-exit-range-start' property specifies the start of the [=animation trigger=]’s
associated [=exit range=].

## The 'animation-trigger-exit-range-end' property ## {#animation-trigger-exit-range-end}

<pre class="propdef">
Name: animation-trigger-exit-range-end
Value: [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: normal
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-exit-range-end/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-exit-range-end' property specifies the end of the [=animation trigger=]’s
associated [=exit range=].

## The 'animation-trigger' property ## {#animation-trigger}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason not to define this shorthand in the same section as the longhand properties it is a short-hand for?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I started with everything next to the short-hand, but later had to move more and properties close to the definition of Trigger below. I'll refactor it now anyway, to have the properties here, and the definitions in web-animaitons-1, as you said.


The 'animation-trigger' property is a [=shorthand property|shorthand=]
that sets 'animation-trigger-type', 'animation-trigger-timeline',
'animation-trigger-range-start', 'animation-trigger-range-end',
'animation-trigger-exit-range-start', and 'animation-trigger-exit-range-end'
together in a single declaration,
specifying the [=animation trigger=] for an animation.

<pre class='propdef'>
Name: animation-trigger
Value: <<single-animation-trigger>>#
Initial: see individual properties
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: see individual properties
Canonical order: per grammar
Animation Type: not animatable
</pre>

<pre class=prod>
<dfn>&lt;single-animation-trigger></dfn> = <<single-animation-trigger-type>> || [ none | auto | [ [ <<dashed-ident>> | <<scroll()>> | <<view()>> ] [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]{0,4} ] ]
</pre>

# Animation Events # {#events}

Expand Down
140 changes: 139 additions & 1 deletion web-animations-1/Overview.bs
View file
Open in desktop
Expand Up @@ -98,7 +98,7 @@ Repository: w3c/csswg-drafts
Test Suite: https://github.com/web-platform-tests/wpt/tree/master/web-animations

Ignored Terms: double, boolean, unsigned long, unrestricted double, (unrestricted double or DOMString)
Ignored Vars: did seek, synchronously notify, auto-rewind
Ignored Vars: did seek, synchronously notify, auto-rewind, did trigger
Markup Shorthands: markdown yes
Include Mdn Panels: no
</pre>
Expand Down Expand Up @@ -772,6 +772,9 @@ Animation Frames {#animation-frame-loop}
* Updating the [=animation/current time=] of any [=animations=]
[=associated with a timeline|associated with=] the timeline.

* Updating the [=animation trigger state=] of any [=animation trigger=]
[=associated with a timeline|associated with=] the timeline.

* Running the [=update an animation's finished state=] procedure
for any animations whose [=animation/current time=] has been updated.

Expand Down Expand Up @@ -3537,6 +3540,141 @@ Calculating progress {#core-animation-effect-calculations}
The final output <dfn>iteration progress</dfn> of an [=animation effect=]
is simply its [=transformed progress=].

Animation Triggers {#triggers}
-----------------

### Overview ### {#triggers-overview}

An <dfn export>animation trigger</dfn> is used to control the playback
of its associated [=animation=] for time-driven animations.
Like animations, [=animation triggers=] are associated with a [=timeline=]
and are attached to an [=animation attachment range|attachment range=].

Issue: Should there be any effect of triggers on scroll-driven animations?

### Animation Trigger State ### {#trigger-state}

An [=animation trigger=] |trigger| with [=animation trigger type=] |type|
has an internal <dfn export lt="animation trigger state">state</dfn> that can be one of the following:

<dl dfn-for="animation trigger state" dfn-type=value>
<dt><dfn>idle</dfn>
<dd>
The [=animation effect=] associated with |trigger| remains in
its [=animation effect/before phase=] and stays at zero [=animation/start time=].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still don't quite get the hierarchy here. This suggests an animation effect is associated with a trigger but previous we said a trigger is associated with an animation. Which is it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, the relation here should be indirect via the animation. The trigger is associated to the animation. The required behavior of the animation is to "hold its effect in a 'just before playing' state". I'll try to fix that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, I think it's better now.


<dt><dfn>primary</dfn>
<dd>
The ''primary'' effect defined by |type| is applied to its associated [=animation=].

<dt><dfn>inverse</dfn>
<dd>
The ''inverse'' effect defined by |type| is applied to its associated [=animation=].

</dl>

Issue: Do we need a formal resolution on the spec of the idle state?

The [=animation trigger state=] |state| of an [=animation trigger=] |trigger|
is controlled by the [=animation attachment range|attachment range=] it is attached to,
given a flag |did trigger|, as follows:

<dl class=switch>
: If |trigger|’s [=local time=] is [=unresolved=],
::
Then |state| is ''animation trigger state/idle'', and |did trigger| is set to false.

: Otherwise,
::

<dl class=switch>
: If |trigger| is inside its [=active interval=],
::
Then |state| is ''animation trigger state/primary'', and |did trigger| is set to true.

: Otherwise,
::

<dl class=switch>
: If |did trigger| flag is false,
::
Then |state| is ''animation trigger state/idle''.

: Otherwise,
::
|state| is ''animation trigger state/inverse''.

</dl>

</dl>

</dl>

### Animation Trigger Types ### {#trigger-types}

The behavior an [=animation trigger=] applies to its associated [=animation=]’s
playback is defined by its <dfn export>animation trigger type</dfn>,
which can be one of the following:

<dl dfn-type=value dfn-for='animation trigger type'>
<dt><dfn>once</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.

<dt><dfn>repeat</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.
The ''inverse'' behavior is resetting the [=animation trigger state=] back to ''animation trigger state/idle''.

<dt><dfn>alternate</dfn>
<dd>
<dl class=switch>
: if the |did trigger| flag is false,
::
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.

: Otherwise,
::
The ''primary'' behavior is [=reverse an animation|reversing=] the associated animation.

</dl>

The ''inverse'' behavior is [=reverse an animation|reversing=] the associated animation.

<dt><dfn>state</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering or resuming=] the associated animation.
The ''inverse'' behavior is [=pause an animation|pausing=] the associated animation.
</dl>

Issue: Need to bike-shed the name for type "state" type.

### Animation Trigger Ranges ### {#trigger-ranges}

An [=animation trigger=] has at least one [=animation attachment range|range=],
its <dfn>default range</dfn>, which defines its [=active interval=].
This range defines when the [=animation trigger|trigger=] is in its ''animation trigger state/primary'' state,
as specified in [[#trigger-state]].

An [=animation trigger=] may also have a second [=animation attachment range|range=],
the <dfn>exit range</dfn>. The [=exit range=] is used to replace [=default range=] and extend
the [=active interval=] of an [=animation trigger=] |trigger| as follows:

<dl class=switch>
: If |trigger| is inside its [=active interval=],
::
It’s attached to its [=exit range=].

: Otherwise,
::
It’s attached to its [=default range=].

</dl>

Issue: Should we specify that that exit range’s edges can only be equal to or greater than the default range’s edges?

Issue: Do we need to specify the process for determining the effective attachment range in the HTML Processing Model?


<!-- End of timing model -->

Expand Down