Fluentui: Animation documentation is lacking

[phkuo]

The new animation documentation is located here:
https://developer.microsoft.com/en-us/fabric#/styles/web/motion

However there are a few problems with it.

• It should mention where you can actually find the CSS class in order to import it.
• The animations exist in both core (as a class) and OUFR (as code), which means they could potentially get out of sync.
• Documentation for the other animations is gone, are they deprecated? Used to be this: https://developer.microsoft.com/en-us/fabric#/styles/animations?fabricVer=6
• Instead of videos we should just have live code... the videos don't play reliably for me.
• We should describe how the durations and timing functions are actually used. The durations also don't match up with official Fluent documentation: https://docs.microsoft.com/en-us/windows/uwp/design/motion/timing-and-easing

@ecraig12345 @Jahnp

[joehillerman]

I am currently trying to add animations to a component when it mounts, unmounts and updates; but I have no clue where to even start with OUFR. I might end up consuming a third party react library for all my animation needs.

[joschect]

@phkuo this is a good request. We'll get on improving the documentation.

@dzearing or @Jahnp Do you know who knows most about animations and who could help out with this?

[phkuo]

This is what I've ascertained so far about using animations:
1) The animations are either available as a string variable representing a CSS class, or as an IStyle for use with CSS-in-JS. In either case, you apply the class/IStyle at the moment you want the animation to start. For example, you can hardcode a slideIn animation on an element, and it will always animate with that slideIn when it first renders or re-renders. If you want to do a fadeOut, you'd wait until you get the event to remove the element, then apply the fadeout class/IStyle.
2) The animations are constructed using the durations and timing functions, which are also provided as variables. In both CSS and CSS-in-JS, you can simply overwrite these to customize their values. What's less obvious is if you want to, for example, "wait for the fadeOut animation to end, then remove the element". You have to look up the duration variable used for the selected animation and use that to wait on the animation, but last time I tried that the timing still didn't work out (possibly because the timing function did weird things to it?), so for my wait time I tripled the duration. Anyways, the point is, there's no good way to figure out what the duration of an animation is in order to trigger an event to happen after it.

[dzearing]

Recommend that before we start documenting css-in-js imports of animations, we do the right thing here. I think suggesting to import animations from @uifabric/styling might paint things into a corner. Instead it would be ideal to have the theme provide animations, so that we can evolve them over time and users can opt in, and potentially override, in the theme.

There are a couple of proposals I have:

Option 1. We split animations our from fabric core css and add a consumption guide.

Possibly, we could have a "stylesheet urls" section in the theme to auto-add stylesheets as required.

Pros:

• Splitting means smaller bundle size
• Easy to consume (use class names)
• Framework agnostic

Cons:

• No type safety
• No control (can't specify a "motion scale" token in theme)
• No animations when you forget to include the css.
• Doesn't "come with" theme

Option 2. Animations accessible through theme via class names.

This requires that any element which wants to use animations accesses them via contextual theme.

We should provide multiple solutions to access the theme:

1. a styled like helper to access the contextual theme.

styled.div(p => [
  p.theme.animations.fadeIn40
]);

1. a hoc to inject theme into a component (withTheme)

export const MyComponent = withTheme(MyComponentBase);
...render() {
   return <div className={ this.props.theme.animations.fadeIn40 } />;
}

1. a hook to get theme

const MyComponent = () => {
  const theme = useTheme();

  return <div className={theme.animations.fadeIn40} />;
};

Pros:

• The theme drives the animation classnames, which means they're user overridable, and can change as the design system changes.
• Type safety
• Possible to derive programmatically based on theme values (less/more motion)

Cons:

• Framework specific (could possibly work with option 1 as well.)

[phkuo]

I would love to see 2 someday, but not until we have a firm idea of how animations are used, how they are composed, and what animations look like in different themes. I think we should start with 1 for now until we have more concrete experience with animations. (Additionally, we haven't even updated animations since Fluent.)

[ecraig12345]

We have some FluentMotion constants, but no indication of how to use them. @Jahnp could you or someone else from the design side help provide guidance on this? I think getting our existing motion constants documented on the website's Motion page should be the top priority (it's also the easiest).

[horsfallnathan]

Could someone show a sample code of how a simple animation is implemented in React using UI Fabric Motion. I just can't find an example out there.

[phkuo]

@horsfallnathan
Using CSS-in-JS, inside Component.styles.ts:

import {
  AnimationStyles,
  AnimationVariables // you can use this to customize things like duration or delay
} from 'office-ui-fabric-react/lib/Styling';

export const getStyles = (props: IFooStyleProps): IFooStyles => {
  return {
    root: {
      ...AnimationStyles.slideUpOut10
    }
  };
}

[aneeshack4]

@horsfallnathan Have you looked at AnimationExample.tsx?

[horsfallnathan]

@horsfallnathan Have you looked at AnimationExample.tsx?

This helps thanks.

[sven5]

I'd like to use UI Fabric with Blazor. Currently, it seems that animation isn't possible with Fabric Core/plain css, is it?
I guess that at least, I must set the animation css class on page load through js.

Thanks