From 42c331bbf2326985bd716793098628cddb3cf28a Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 19 Oct 2018 14:42:30 +0100 Subject: [PATCH] docs: update animations with `@publicApi` tags (#26595) PR Close #26595 --- packages/animations/src/animation_builder.ts | 4 +- packages/animations/src/animation_metadata.ts | 68 ++++++++++++++++++- .../src/players/animation_player.ts | 4 +- .../animations/animations.d.ts | 2 - 4 files changed, 71 insertions(+), 7 deletions(-) diff --git a/packages/animations/src/animation_builder.ts b/packages/animations/src/animation_builder.ts index 5d8d826d31..7393878b21 100644 --- a/packages/animations/src/animation_builder.ts +++ b/packages/animations/src/animation_builder.ts @@ -52,10 +52,11 @@ import {AnimationPlayer} from './players/animation_player'; * } * ``` * + * @publicApi */ export abstract class AnimationBuilder { /** - * Builds a factory for producing a defined animation. + * Builds a factory for producing a defined animation. * @param animation A reusable animation definition. * @returns A factory object that can create a player for the defined animation. * @see `animate()` @@ -66,6 +67,7 @@ export abstract class AnimationBuilder { /** * A factory object returned from the `AnimationBuilder`.`build()` method. * + * @publicApi */ export abstract class AnimationFactory { /** diff --git a/packages/animations/src/animation_metadata.ts b/packages/animations/src/animation_metadata.ts index 6d7c247c68..c3a533d931 100755 --- a/packages/animations/src/animation_metadata.ts +++ b/packages/animations/src/animation_metadata.ts @@ -12,9 +12,11 @@ export interface ɵStyleData { [key: string]: string|number; } /** -* Represents animation-step timing parameters for an animation step. -* @see `animate()` -*/ + * Represents animation-step timing parameters for an animation step. + * @see `animate()` + * + * @publicApi + */ export declare type AnimateTimings = { /** * The full duration of an animation step. A number and optional time unit, @@ -53,6 +55,8 @@ export declare type AnimateTimings = { * * Programmatic animations built using the `AnimationBuilder` service also * make use of `AnimationOptions`. + * + * @publicApi */ export declare interface AnimationOptions { /** @@ -74,6 +78,8 @@ export declare interface AnimationOptions { * Adds duration options to control animation styling and timing for a child animation. * * @see `animateChild()` + * + * @publicApi */ export declare interface AnimateChildOptions extends AnimationOptions { duration?: number|string; } @@ -82,6 +88,8 @@ export declare interface AnimateChildOptions extends AnimationOptions { duration * * A corresponding function defines a set of parameters for each category, and * collects them into a corresponding `AnimationMetadata` object. + * + * @publicApi */ export const enum AnimationMetadataType { /** @@ -153,17 +161,23 @@ export const enum AnimationMetadataType { /** * Specifies automatic styling. + * + * @publicApi */ export const AUTO_STYLE = '*'; /** * Base for animation data structures. + * + * @publicApi */ export interface AnimationMetadata { type: AnimationMetadataType; } /** * Contains an animation trigger. Instantiated and returned by the * `trigger()` function. + * + * @publicApi */ export interface AnimationTriggerMetadata extends AnimationMetadata { /** @@ -185,6 +199,8 @@ export interface AnimationTriggerMetadata extends AnimationMetadata { /** * Encapsulates an animation state by associating a state name with a set of CSS styles. * Instantiated and returned by the `state()` function. + * + * @publicApi */ export interface AnimationStateMetadata extends AnimationMetadata { /** @@ -206,6 +222,8 @@ export interface AnimationStateMetadata extends AnimationMetadata { /** * Encapsulates an animation transition. Instantiated and returned by the * `transition()` function. + * + * @publicApi */ export interface AnimationTransitionMetadata extends AnimationMetadata { /** @@ -230,6 +248,8 @@ export interface AnimationTransitionMetadata extends AnimationMetadata { * Encapsulates a reusable animation, which is a collection of individual animation steps. * Instantiated and returned by the `animation()` function, and * passed to the `useAnimation()` function. + * + * @publicApi */ export interface AnimationReferenceMetadata extends AnimationMetadata { /** @@ -247,6 +267,8 @@ export interface AnimationReferenceMetadata extends AnimationMetadata { /** * Encapsulates an animation query. Instantiated and returned by * the `query()` function. + * + * @publicApi */ export interface AnimationQueryMetadata extends AnimationMetadata { /** @@ -266,6 +288,8 @@ export interface AnimationQueryMetadata extends AnimationMetadata { /** * Encapsulates a keyframes sequence. Instantiated and returned by * the `keyframes()` function. + * + * @publicApi */ export interface AnimationKeyframesSequenceMetadata extends AnimationMetadata { /** @@ -277,6 +301,8 @@ export interface AnimationKeyframesSequenceMetadata extends AnimationMetadata { /** * Encapsulates an animation style. Instantiated and returned by * the `style()` function. + * + * @publicApi */ export interface AnimationStyleMetadata extends AnimationMetadata { /** @@ -292,6 +318,8 @@ export interface AnimationStyleMetadata extends AnimationMetadata { /** * Encapsulates an animation step. Instantiated and returned by * the `animate()` function. + * + * @publicApi */ export interface AnimationAnimateMetadata extends AnimationMetadata { /** @@ -307,6 +335,8 @@ export interface AnimationAnimateMetadata extends AnimationMetadata { /** * Encapsulates a child animation, that can be run explicitly when the parent is run. * Instantiated and returned by the `animateChild` function. + * + * @publicApi */ export interface AnimationAnimateChildMetadata extends AnimationMetadata { /** @@ -320,6 +350,8 @@ export interface AnimationAnimateChildMetadata extends AnimationMetadata { /** * Encapsulates a reusable animation. * Instantiated and returned by the `useAnimation()` function. + * + * @publicApi */ export interface AnimationAnimateRefMetadata extends AnimationMetadata { /** @@ -337,6 +369,8 @@ export interface AnimationAnimateRefMetadata extends AnimationMetadata { /** * Encapsulates an animation sequence. * Instantiated and returned by the `sequence()` function. + * + * @publicApi */ export interface AnimationSequenceMetadata extends AnimationMetadata { /** @@ -354,6 +388,8 @@ export interface AnimationSequenceMetadata extends AnimationMetadata { /** * Encapsulates an animation group. * Instantiated and returned by the `{@link animations/group group()}` function. + * + * @publicApi */ export interface AnimationGroupMetadata extends AnimationMetadata { /** @@ -371,6 +407,8 @@ export interface AnimationGroupMetadata extends AnimationMetadata { /** * Encapsulates animation query options. * Passed to the `query()` function. + * + * @publicApi */ export declare interface AnimationQueryOptions extends AnimationOptions { /** @@ -391,6 +429,8 @@ export declare interface AnimationQueryOptions extends AnimationOptions { /** * Encapsulates parameters for staggering the start times of a set of animation steps. * Instantiated and returned by the `stagger()` function. + * + * @publicApi **/ export interface AnimationStaggerMetadata extends AnimationMetadata { /** @@ -610,6 +650,8 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati * style({ background: "red" })) * ]) * ``` + * + * @publicApi */ export function animate( timings: string | number, styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | @@ -647,6 +689,8 @@ export function animate( * When called within a `sequence()` or a * `transition()` call, does not continue to the next * instruction until all of the inner animation steps have completed. + * + * @publicApi */ export function group( steps: AnimationMetadata[], options: AnimationOptions | null = null): AnimationGroupMetadata { @@ -683,6 +727,7 @@ export function group( * execution continues to the next instruction only after each of the inner animation * steps have completed. * + * @publicApi **/ export function sequence(steps: AnimationMetadata[], options: AnimationOptions | null = null): AnimationSequenceMetadata { @@ -726,6 +771,7 @@ export function sequence(steps: AnimationMetadata[], options: AnimationOptions | * animate("1s", style({ height: "*" })) * ``` * + * @publicApi **/ export function style( tokens: '*' | {[key: string]: string | number} | @@ -759,6 +805,8 @@ export function style( * Use the `transition()` function to animate between states. * When a state is active within a component, its associated styles persist on the element, * even when the animation ends. + * + * @publicApi **/ export function state( name: string, styles: AnimationStyleMetadata, @@ -808,6 +856,8 @@ export function state( * style({ backgroundColor: "black" }) // offset = 1 * ])) *``` + + * @publicApi */ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata { return {type: AnimationMetadataType.Keyframes, steps}; @@ -978,6 +1028,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * transition('false <=> true', animate(500)) * ]) * ``` + * + * @publicApi **/ export function transition( stateChangeExpr: string | ((fromState: string, toState: string, element?: any, @@ -1029,6 +1081,8 @@ export function transition( * If any of the passed-in parameter values are missing from this call, * the default values are used. If one or more parameter values are missing before a step is * animated, `useAnimation()` throws an error. + * + * @publicApi */ export function animation( steps: AnimationMetadata | AnimationMetadata[], @@ -1052,6 +1106,8 @@ export function animation( * Note that this feature designed to be used with `query()` and it will only work * with animations that are assigned using the Angular animation library. CSS keyframes * and transitions are not handled by this API. + * + * @publicApi */ export function animateChild(options: AnimateChildOptions | null = null): AnimationAnimateChildMetadata { @@ -1065,6 +1121,8 @@ export function animateChild(options: AnimateChildOptions | null = null): * @param options An options object that can contain a delay value for the start of * the animation, and additional override values for developer-defined parameters. * @return An object that contains the animation parameters. + * + * @publicApi */ export function useAnimation( animation: AnimationReferenceMetadata, @@ -1156,6 +1214,8 @@ export function useAnimation( * } * } * ``` + * + * @publicApi */ export function query( selector: string, animation: AnimationMetadata | AnimationMetadata[], @@ -1240,6 +1300,8 @@ export function query( * ]) * ]) * ``` + * + * @publicApi */ export function stagger( timings: string | number, diff --git a/packages/animations/src/players/animation_player.ts b/packages/animations/src/players/animation_player.ts index 3813a9a44f..3a183db7c2 100644 --- a/packages/animations/src/players/animation_player.ts +++ b/packages/animations/src/players/animation_player.ts @@ -14,8 +14,9 @@ import {scheduleMicroTask} from '../util'; * * @see `AnimationBuilder` * @see `AnimationFactory` - * @see `animate()` + * @see `animate()` * + * @publicApi */ export interface AnimationPlayer { /** @@ -112,6 +113,7 @@ export interface AnimationPlayer { * @see `AnimationPlayer` * @see `GroupPlayer` * + * @publicApi */ export class NoopAnimationPlayer implements AnimationPlayer { private _onDoneFns: Function[] = []; diff --git a/tools/public_api_guard/animations/animations.d.ts b/tools/public_api_guard/animations/animations.d.ts index 32965de7d6..f8dce966fe 100644 --- a/tools/public_api_guard/animations/animations.d.ts +++ b/tools/public_api_guard/animations/animations.d.ts @@ -32,7 +32,6 @@ export declare abstract class AnimationBuilder { abstract build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory; } -/** @experimental */ export interface AnimationEvent { disabled: boolean; element: any; @@ -212,7 +211,6 @@ export declare function transition(stateChangeExpr: string | ((fromState: string [key: string]: any; }) => boolean), steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationTransitionMetadata; -/** @experimental */ export declare function trigger(name: string, definitions: AnimationMetadata[]): AnimationTriggerMetadata; export declare function useAnimation(animation: AnimationReferenceMetadata, options?: AnimationOptions | null): AnimationAnimateRefMetadata;