chore: adds API docs for fast-colors and fast-animation (#3359)

* wire api-extractor to library

* wire animation packge to doc prep script

* wire docs to build and ci

* add api extractor to fast-colors

* document fast-animation

* export animate so that it can be properly documented

* hook up build and test to doc generation

* document fast-colors

* sort sidebar

packages/utilities/fast-animation/api-extractor.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    "mainEntryPointFilePath": "dist/index.d.ts",
+    "apiReport": {
+        "enabled": true,
+        "reportFolder": "docs",
+        "reportFileName": "api-report.md"
+    },
+    "docModel": {
+        "enabled": true,
+        "apiJsonFilePath": "dist/fast-animation.api.json"
+    },
+    "dtsRollup": {
+        "enabled": true
+    }
+}

packages/utilities/fast-animation/docs/api-report.md

@@ -0,0 +1,91 @@
+## API Report File for "@microsoft/fast-animation"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @public
+export abstract class Animate {
+    constructor(element: HTMLElement, options?: AnimateConfig, effectTiming?: EffectTiming);
+    addKeyframes: (keyframes: Partial<Keyframe>[]) => void;
+    cancel: () => void;
+    effectTiming: EffectTiming;
+    finish: () => void;
+    readonly keyframeEffect: KeyframeEffect;
+    readonly keyframes: Keyframe[];
+    // Warning: (ae-forgotten-export) The symbol "AnimationMode" needs to be exported by the entry point index.d.ts
+    protected mode: AnimationMode;
+    onCancel: () => void;
+    // (undocumented)
+    onFinish: () => void;
+    // Warning: (ae-forgotten-export) The symbol "AnimateConfig" needs to be exported by the entry point index.d.ts
+    options: AnimateConfig;
+    pause: () => void;
+    play: () => void;
+    reverse: () => void;
+    }
+
+// @public
+export class AnimateFrom extends Animate {
+    // (undocumented)
+    protected mode: AnimationMode;
+}
+
+// @public
+export class AnimateGroup {
+    constructor(animations: Array<AnimateTo | AnimateFrom>);
+    cancel: () => void;
+    finish: () => void;
+    onFinish: () => void;
+    pause: () => void;
+    play(): void;
+    reverse(): void;
+}
+
+// @public
+export class AnimateSequence {
+    constructor(animations: Array<AnimateTo | AnimateFrom>);
+    cancel: () => void;
+    finish: () => void;
+    onFinish: () => void;
+    pause: () => void;
+    play: () => void;
+    reverse: () => void;
+}
+
+// @public
+export class AnimateTo extends Animate {
+    // (undocumented)
+    protected mode: AnimationMode;
+}
+
+// @public
+export function cubicBezier(name: "linear" | "easeOut" | "easeOutSmooth" | "easeIn" | "drillIn" | "backToApp" | "appToApp" | "fastIn" | "fastOut" | "fastInOut" | "exponential" | "fastInFortySevenPercent" | "exponentialReversed" | "navPane" | /* @deprecated */ string): string;
+
+// @public
+export function fadeIn(element: HTMLElement, effectTiming?: EffectTiming): AnimateTo;
+
+// @public
+export function fadeOut(element: HTMLElement, effectTiming?: EffectTiming): AnimateTo;
+
+// Warning: (ae-forgotten-export) The symbol "ScrollTrigger" needs to be exported by the entry point index.d.ts
+//
+// @public
+export class ScrollTrigger extends ScrollTrigger_2 {
+    protected update(): void;
+}
+
+// @public
+export class ViewEnterTrigger extends ScrollTrigger_2 {
+    protected update(): void;
+}
+
+// @public
+export class ViewExitTrigger extends ScrollTrigger_2 {
+    protected update(): void;
+}
+
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/utilities/fast-animation/lib/animate/index.ts

@@ -1,3 +1,7 @@
+/**
+ * Describes the animation properties
+ * @public
+ */
 export interface AnimateConfig {
     /**
      * The x position change of the animation
@@ -37,7 +41,7 @@ export interface AnimateConfig {
     /**
      * The scale factor of the animation
      */
-    scale?: ScaleFactor;
+    scale?: number | [number, number];
 
     /**
      * The opacity after the animation
@@ -57,6 +61,7 @@ export interface AnimateConfig {
 
 /**
  * Enumerates all properties that can be animated, outside of properties supplied directly via Animate.addKeyframes()
+ * @public
  */
 export interface AnimationProperties {
     top?: string;
@@ -67,13 +72,10 @@ export interface AnimationProperties {
     transform?: string;
 }
 
-/**
- * Scale factor is either a single number that scales both x and y dependently, or two numbers that scale x and y respectively
- */
-export type ScaleFactor = number | [number, number];
-
 /**
  * Animation mode describes if an animation should animate toward an elements natural position or away from it
+ *
+ * @internal
  */
 export enum AnimationMode {
     animateTo,
@@ -83,7 +85,7 @@ export enum AnimationMode {
 /**
  * Maps css property names to animation options
  */
-export interface PropertyMap {
+interface PropertyMap {
     opacity: string[];
     transform: string[];
     top: string[];
@@ -92,6 +94,11 @@ export interface PropertyMap {
     right: string[];
 }
 
+/**
+ * Base animate type. This is extended by {@link @microsoft/fast-animation#AnimateTo} and {@link @microsoft/fast-animation#AnimateFrom}.
+ *
+ * @public
+ */
 export default abstract class Animate {
     /**
      * A mapping between animation options and the css property names they apply to

packages/utilities/fast-animation/lib/animateFrom/index.ts

@@ -1,5 +1,11 @@
 import Animate, { AnimationMode } from "../animate";
 
-export default class extends Animate {
+/**
+ * An animation from provided property values to the element's current values.
+ * Extends {@link @microsoft/fast-animation#Animate}.
+ *
+ * @public
+ */
+export default class AnimateFrom extends Animate {
     protected mode: AnimationMode = AnimationMode.animateFrom;
 }

packages/utilities/fast-animation/lib/animateGroup/index.ts

@@ -2,6 +2,10 @@ import AnimateTo from "../animateTo";
 import AnimateFrom from "../animateFrom";
 import { invokeFunctionForEach } from "../utilities/invokeFunctionForEach";
 
+/**
+ * Groups {@link @microsoft/fast-animation#AnimateTo} and {@link @microsoft/fast-animation#AnimateFrom} instances, providing a single API to operate on all of them.
+ * @public
+ */
 class AnimateGroup {
     /**
      * Stores the onFinish callback

packages/utilities/fast-animation/lib/animateSequence/index.ts

@@ -2,6 +2,10 @@ import AnimateTo from "../animateTo";
 import AnimateFrom from "../animateFrom";
 import { invokeFunctionForEach } from "../utilities/invokeFunctionForEach";
 
+/**
+ * Animate a collection of {@link @microsoft/fast-animation#AnimateTo} and {@link @microsoft/fast-animation#AnimateFrom} in sequence.
+ * @public
+ */
 class AnimateSequence {
     /**
      * onFinish callback method

packages/utilities/fast-animation/lib/animateTo/index.ts

@@ -1,5 +1,10 @@
 import Animate, { AnimationMode } from "../animate";
 
-export default class extends Animate {
+/**
+ * An animation to provided property values from the element's current values.
+ * Extends {@link @microsoft/fast-animation#Animate}.
+ * @public
+ */
+export default class AnimateTo extends Animate {
     protected mode: AnimationMode = AnimationMode.animateTo;
 }

packages/utilities/fast-animation/lib/curves/index.ts

@@ -1,8 +1,12 @@
 import * as bezierCurves from "./config";
-
+/**
+ * Coordinates for a cubic bezier curve.
+ * @public
+ */
 export type BezierCurvePoint = [number, number];
 /**
  * Defines interface for a cubic bezier curve
+ * @public
  */
 export interface BezierCurve {
     /**
@@ -18,6 +22,8 @@ export interface BezierCurve {
 
 /**
  * Formats a cubic bezier config into a cubic bezier string
+ *
+ * @public
  */
 export function formatCubicBezier(points: BezierCurve): string {
     if (
@@ -34,6 +40,29 @@ export function formatCubicBezier(points: BezierCurve): string {
     return `cubic-bezier(${p0[0]}, ${p0[1]}, ${p1[0]}, ${p1[1]})`;
 }
 
-export function cubicBezier(name: string): string {
+/**
+ * Get a cubic bezier curve, formatted as a string, by name.
+ * @param name - the name of the bezier curve to use.
+ *
+ * @public
+ */
+export function cubicBezier(
+    name:
+        | "linear"
+        | "easeOut"
+        | "easeOutSmooth"
+        | "easeIn"
+        | "drillIn"
+        | "backToApp"
+        | "appToApp"
+        | "fastIn"
+        | "fastOut"
+        | "fastInOut"
+        | "exponential"
+        | "fastInFortySevenPercent"
+        | "exponentialReversed"
+        | "navPane"
+        | /* @deprecated */ string
+): string {
     return bezierCurves.hasOwnProperty(name) ? formatCubicBezier(bezierCurves[name]) : "";
 }

packages/utilities/fast-animation/lib/fade/index.ts

@@ -39,13 +39,17 @@ export function applyFade(
 
 /**
  * Creates an animation to fade an element into view
+ *
+ * @public
  */
 export function fadeIn(element: HTMLElement, effectTiming: EffectTiming = {}): AnimateTo {
     return applyFade(element, fadeInKeyframes, effectTiming);
 }
 
 /**
  * Creates an animation to fade an element out of view
+ *
+ * @public
  */
 export function fadeOut(
     element: HTMLElement,

packages/utilities/fast-animation/lib/index.ts

@@ -2,6 +2,7 @@ import AnimateTo from "./animateTo";
 import AnimateFrom from "./animateFrom";
 import AnimateGroup from "./animateGroup";
 import AnimateSequence from "./animateSequence";
+import Animate from "./animate";
 
 import { fadeIn, fadeOut } from "./fade";
 import { cubicBezier } from "./curves";
@@ -11,6 +12,7 @@ import ViewEnterTrigger from "./triggers/ViewEnterTrigger";
 import ViewExitTrigger from "./triggers/ViewExitTrigger";
 
 export {
+    Animate,
     AnimateFrom,
     AnimateGroup,
     AnimateSequence,

packages/utilities/fast-animation/lib/triggers/ScrollTrigger.ts

@@ -3,6 +3,8 @@ import ScrollBase, { ScrollTriggerSubscription } from "./ScrollBase";
 
 /**
  * Utility for registering element/callback pairs where the callback will be called on scroll while the element is in view.
+ *
+ * @public
  */
 export default class ScrollTrigger extends ScrollBase {
     /**

packages/utilities/fast-animation/lib/triggers/ViewEnterTrigger.ts

@@ -3,6 +3,8 @@ import ScrollBase, { ScrollTriggerSubscription } from "./ScrollBase";
 
 /**
  * Utility for registering element/callback pairs where the callback will be called when the element enters the view-port
+ *
+ * @public
  */
 export default class ViewEnterTrigger extends ScrollBase {
     /**

packages/utilities/fast-animation/lib/triggers/ViewExitTrigger.ts

@@ -2,7 +2,9 @@ import isElementInView from "../utilities/isElementInView";
 import ScrollBase, { ScrollTriggerSubscription } from "./ScrollBase";
 
 /**
- * Utility for registering element/callback pairs where the callback will be called when the element exits the view-port
+ * Utility for registering element/callback pairs where the callback will be invoked when the element exits the view-port
+ *
+ * @public
  */
 export default class ViewExitTrigger extends ScrollBase {
     /**

packages/utilities/fast-animation/package.json

@@ -16,14 +16,16 @@
   },
   "main": "dist/index.js",
   "scripts": {
-    "build": "tsc -p ./lib/tsconfig.json",
+    "build": "tsc -p ./lib/tsconfig.json && yarn doc",
     "build:app": "webpack --mode=production",
     "coverage": "jest --coverage",
+    "doc": "api-extractor run --local",
+    "doc:ci": "api-extractor run",
     "prepare": "yarn build",
     "prettier": "prettier --config ../../../.prettierrc --write \"**/*.{ts,tsx}\"",
     "prettier:diff": "prettier --config ../../../.prettierrc \"**/*.{ts,tsx}\" --list-different",
     "start": "node_modules/.bin/webpack-dev-server --progress",
-    "test": "yarn unit-tests && yarn build:app",
+    "test": "yarn unit-tests && yarn build:app && yarn doc:ci",
     "eslint": "eslint . --ext .ts,.tsx",
     "eslint:fix": "eslint . --ext .ts,.tsx --fix",
     "unit-tests": "jest --runInBand",
@@ -68,6 +70,7 @@
     "@babel/core": "^7.0.0",
     "@babel/preset-env": "^7.1.0",
     "@babel/preset-react": "^7.0.0",
+    "@microsoft/api-extractor": "^7.7.13",
     "@microsoft/eslint-config-fast-dna": "^1.1.3",
     "@types/jest": "^25.2.1",
     "@types/node": "^7.0.22",