build: validate CDK public API using ts-api-guardian (#14131)

Author: devversion

.circleci/config.yml

@@ -90,7 +90,7 @@ jobs:
 
       # TODO(jelbourn): Update this command to run all tests if the Bazel issues have been fixed.
       - run: bazel build src/...
-      - run: bazel test src/...
+      - run: bazel test src/... tools/public_api_guard/...
 
   # ------------------------------------------------------------------------------------------
   # Job that runs the unit tests on locally installed browsers (Chrome and Firefox headless).

WORKSPACE

@@ -17,8 +17,8 @@ http_archive(
 # Add Angular source and Bazel rules.
 http_archive(
   name = "angular",
-  url = "https://github.com/angular/angular/archive/7.0.3.zip",
-  strip_prefix = "angular-7.0.3",
+  url = "https://github.com/angular/angular/archive/2ec05415e24137d44f24b07202c34c5054c968ed.zip",
+  strip_prefix = "angular-2ec05415e24137d44f24b07202c34c5054c968ed",
 )
 
 # Add RxJS as repository because those are needed in order to build Angular from source.

tools/public_api_guard/BUILD.bazel

@@ -0,0 +1,9 @@
+package(default_visibility=["//visibility:public"])
+
+load(":generate-guard-tests.bzl", "generate_test_targets")
+
+# TODO(devversion): This currently does not include the CDK portal package because
+# aliases are not supported by ts-api-guardian. Re-add once we found a solution for that.
+
+# Generate the API guard test targets for each golden file in the current package.
+generate_test_targets(glob(["**/*.d.ts"]))

tools/public_api_guard/cdk/a11y.d.ts

@@ -0,0 +1,178 @@
+export declare class A11yModule {
+}
+
+export declare class ActiveDescendantKeyManager<T> extends ListKeyManager<Highlightable & T> {
+    setActiveItem(index: number): void;
+    setActiveItem(item: T): void;
+}
+
+export declare const ARIA_DESCRIBER_PROVIDER: {
+    provide: typeof AriaDescriber;
+    deps: (Optional[] | InjectionToken<any>)[];
+    useFactory: typeof ARIA_DESCRIBER_PROVIDER_FACTORY;
+};
+
+export declare function ARIA_DESCRIBER_PROVIDER_FACTORY(parentDispatcher: AriaDescriber, _document: any): AriaDescriber;
+
+export declare class AriaDescriber implements OnDestroy {
+    constructor(_document: any);
+    describe(hostElement: Element, message: string): void;
+    ngOnDestroy(): void;
+    removeDescription(hostElement: Element, message: string): void;
+}
+
+export declare type AriaLivePoliteness = 'off' | 'polite' | 'assertive';
+
+export declare const CDK_DESCRIBEDBY_HOST_ATTRIBUTE = "cdk-describedby-host";
+
+export declare const CDK_DESCRIBEDBY_ID_PREFIX = "cdk-describedby-message";
+
+export declare class CdkAriaLive implements OnDestroy {
+    politeness: AriaLivePoliteness;
+    constructor(_elementRef: ElementRef, _liveAnnouncer: LiveAnnouncer, _contentObserver: ContentObserver, _ngZone: NgZone);
+    ngOnDestroy(): void;
+}
+
+export declare class CdkMonitorFocus implements OnDestroy {
+    cdkFocusChange: EventEmitter<FocusOrigin>;
+    constructor(_elementRef: ElementRef<HTMLElement>, _focusMonitor: FocusMonitor);
+    ngOnDestroy(): void;
+}
+
+export declare class CdkTrapFocus implements OnDestroy, AfterContentInit, DoCheck {
+    autoCapture: boolean;
+    enabled: boolean;
+    focusTrap: FocusTrap;
+    constructor(_elementRef: ElementRef<HTMLElement>, _focusTrapFactory: FocusTrapFactory, _document: any);
+    ngAfterContentInit(): void;
+    ngDoCheck(): void;
+    ngOnDestroy(): void;
+}
+
+export declare const FOCUS_MONITOR_PROVIDER: {
+    provide: typeof FocusMonitor;
+    deps: (Optional[] | typeof NgZone | typeof Platform)[];
+    useFactory: typeof FOCUS_MONITOR_PROVIDER_FACTORY;
+};
+
+export declare function FOCUS_MONITOR_PROVIDER_FACTORY(parentDispatcher: FocusMonitor, ngZone: NgZone, platform: Platform): FocusMonitor;
+
+export interface FocusableOption extends ListKeyManagerOption {
+    focus(origin?: FocusOrigin): void;
+}
+
+export declare class FocusKeyManager<T> extends ListKeyManager<FocusableOption & T> {
+    setActiveItem(index: number): void;
+    setActiveItem(item: T): void;
+    setFocusOrigin(origin: FocusOrigin): this;
+}
+
+export declare class FocusMonitor implements OnDestroy {
+    constructor(_ngZone: NgZone, _platform: Platform);
+    _onBlur(event: FocusEvent, element: HTMLElement): void;
+    focusVia(element: ElementRef<HTMLElement>, origin: FocusOrigin, options?: FocusOptions): void;
+    focusVia(element: HTMLElement, origin: FocusOrigin, options?: FocusOptions): void;
+    monitor(element: HTMLElement, checkChildren?: boolean): Observable<FocusOrigin>;
+    monitor(element: ElementRef<HTMLElement>, checkChildren?: boolean): Observable<FocusOrigin>;
+    ngOnDestroy(): void;
+    stopMonitoring(element: ElementRef<HTMLElement>): void;
+    stopMonitoring(element: HTMLElement): void;
+}
+
+export interface FocusOptions {
+    preventScroll?: boolean;
+}
+
+export declare type FocusOrigin = 'touch' | 'mouse' | 'keyboard' | 'program' | null;
+
+export declare class FocusTrap {
+    enabled: boolean;
+    constructor(_element: HTMLElement, _checker: InteractivityChecker, _ngZone: NgZone, _document: Document, deferAnchors?: boolean);
+    attachAnchors(): boolean;
+    destroy(): void;
+    focusFirstTabbableElement(): boolean;
+    focusFirstTabbableElementWhenReady(): Promise<boolean>;
+    focusInitialElement(): boolean;
+    focusInitialElementWhenReady(): Promise<boolean>;
+    focusLastTabbableElement(): boolean;
+    focusLastTabbableElementWhenReady(): Promise<boolean>;
+    hasAttached(): boolean;
+}
+
+export declare class FocusTrapFactory {
+    constructor(_checker: InteractivityChecker, _ngZone: NgZone, _document: any);
+    create(element: HTMLElement, deferCaptureElements?: boolean): FocusTrap;
+}
+
+export interface Highlightable extends ListKeyManagerOption {
+    setActiveStyles(): void;
+    setInactiveStyles(): void;
+}
+
+export declare class InteractivityChecker {
+    constructor(_platform: Platform);
+    isDisabled(element: HTMLElement): boolean;
+    isFocusable(element: HTMLElement): boolean;
+    isTabbable(element: HTMLElement): boolean;
+    isVisible(element: HTMLElement): boolean;
+}
+
+export declare function isFakeMousedownFromScreenReader(event: MouseEvent): boolean;
+
+export declare class ListKeyManager<T extends ListKeyManagerOption> {
+    readonly activeItem: T | null;
+    readonly activeItemIndex: number | null;
+    change: Subject<number>;
+    tabOut: Subject<void>;
+    constructor(_items: QueryList<T> | T[]);
+    onKeydown(event: KeyboardEvent): void;
+    setActiveItem(index: number): void;
+    setActiveItem(item: T): void;
+    setFirstItemActive(): void;
+    setLastItemActive(): void;
+    setNextItemActive(): void;
+    setPreviousItemActive(): void;
+    skipPredicate(predicate: (item: T) => boolean): this;
+    updateActiveItem(item: T): void;
+    updateActiveItem(index: number): void;
+    updateActiveItemIndex(index: number): void;
+    withAllowedModifierKeys(keys: ListKeyManagerModifierKey[]): this;
+    withHorizontalOrientation(direction: 'ltr' | 'rtl' | null): this;
+    withTypeAhead(debounceInterval?: number): this;
+    withVerticalOrientation(enabled?: boolean): this;
+    withWrap(shouldWrap?: boolean): this;
+}
+
+export declare type ListKeyManagerModifierKey = 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey';
+
+export interface ListKeyManagerOption {
+    disabled?: boolean;
+    getLabel?(): string;
+}
+
+export declare const LIVE_ANNOUNCER_ELEMENT_TOKEN: InjectionToken<HTMLElement | null>;
+
+export declare function LIVE_ANNOUNCER_ELEMENT_TOKEN_FACTORY(): null;
+
+export declare const LIVE_ANNOUNCER_PROVIDER: Provider;
+
+export declare function LIVE_ANNOUNCER_PROVIDER_FACTORY(parentDispatcher: LiveAnnouncer, liveElement: any, _document: any, ngZone: NgZone): LiveAnnouncer;
+
+export declare class LiveAnnouncer implements OnDestroy {
+    constructor(elementToken: any, _ngZone: NgZone, _document: any);
+    announce(message: string): Promise<void>;
+    announce(message: string, duration?: number): Promise<void>;
+    announce(message: string, politeness?: AriaLivePoliteness, duration?: number): Promise<void>;
+    announce(message: string, politeness?: AriaLivePoliteness): Promise<void>;
+    clear(): void;
+    ngOnDestroy(): void;
+}
+
+export declare const MESSAGES_CONTAINER_ID = "cdk-describedby-message-container";
+
+export interface RegisteredMessage {
+    messageElement: Element;
+    referenceCount: number;
+}
+
+export declare const TOUCH_BUFFER_MS = 650;

tools/public_api_guard/cdk/accordion.d.ts

@@ -0,0 +1,30 @@
+export declare class CdkAccordion implements OnDestroy, OnChanges {
+    readonly _openCloseAllActions: Subject<boolean>;
+    readonly _stateChanges: Subject<SimpleChanges>;
+    readonly id: string;
+    multi: boolean;
+    closeAll(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    openAll(): void;
+}
+
+export declare class CdkAccordionItem implements OnDestroy {
+    protected _expansionDispatcher: UniqueSelectionDispatcher;
+    accordion: CdkAccordion;
+    closed: EventEmitter<void>;
+    destroyed: EventEmitter<void>;
+    disabled: any;
+    expanded: any;
+    expandedChange: EventEmitter<boolean>;
+    readonly id: string;
+    opened: EventEmitter<void>;
+    constructor(accordion: CdkAccordion, _changeDetectorRef: ChangeDetectorRef, _expansionDispatcher: UniqueSelectionDispatcher);
+    close(): void;
+    ngOnDestroy(): void;
+    open(): void;
+    toggle(): void;
+}
+
+export declare class CdkAccordionModule {
+}

tools/public_api_guard/cdk/bidi.d.ts

@@ -0,0 +1,22 @@
+export declare class BidiModule {
+}
+
+export declare class Dir implements Directionality, AfterContentInit, OnDestroy {
+    _rawDir: string;
+    change: EventEmitter<Direction>;
+    dir: Direction;
+    readonly value: Direction;
+    ngAfterContentInit(): void;
+    ngOnDestroy(): void;
+}
+
+export declare const DIR_DOCUMENT: InjectionToken<Document>;
+
+export declare type Direction = 'ltr' | 'rtl';
+
+export declare class Directionality implements OnDestroy {
+    readonly change: EventEmitter<Direction>;
+    readonly value: Direction;
+    constructor(_document?: any);
+    ngOnDestroy(): void;
+}

tools/public_api_guard/cdk/cdk.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: Version;

tools/public_api_guard/cdk/coercion.d.ts

@@ -0,0 +1,10 @@
+export declare function _isNumberValue(value: any): boolean;
+
+export declare function coerceArray<T>(value: T | T[]): T[];
+
+export declare function coerceBooleanProperty(value: any): boolean;
+
+export declare function coerceCssPixelValue(value: any): string;
+
+export declare function coerceNumberProperty(value: any): number;
+export declare function coerceNumberProperty<D>(value: any, fallback: D): number | D;

tools/public_api_guard/cdk/collections.d.ts

@@ -0,0 +1,57 @@
+export declare class ArrayDataSource<T> extends DataSource<T> {
+    constructor(_data: T[] | ReadonlyArray<T> | Observable<T[] | ReadonlyArray<T>>);
+    connect(): Observable<T[] | ReadonlyArray<T>>;
+    disconnect(): void;
+}
+
+export interface CollectionViewer {
+    viewChange: Observable<ListRange>;
+}
+
+export declare abstract class DataSource<T> {
+    abstract connect(collectionViewer: CollectionViewer): Observable<T[] | ReadonlyArray<T>>;
+    abstract disconnect(collectionViewer: CollectionViewer): void;
+}
+
+export declare function getMultipleValuesInSingleSelectionError(): Error;
+
+export declare type ListRange = {
+    start: number;
+    end: number;
+};
+
+export interface SelectionChange<T> {
+    added: T[];
+    removed: T[];
+    source: SelectionModel<T>;
+}
+
+export declare class SelectionModel<T> {
+    changed: Subject<SelectionChange<T>>;
+    onChange: Subject<SelectionChange<T>>;
+    readonly selected: T[];
+    constructor(_multiple?: boolean, initiallySelectedValues?: T[], _emitChanges?: boolean);
+    clear(): void;
+    deselect(...values: T[]): void;
+    hasValue(): boolean;
+    isEmpty(): boolean;
+    isMultipleSelection(): boolean;
+    isSelected(value: T): boolean;
+    select(...values: T[]): void;
+    sort(predicate?: (a: T, b: T) => number): void;
+    toggle(value: T): void;
+}
+
+export interface TreeDataNodeFlattener<T> {
+    expandFlattenedNodes(nodes: T[], expansionModel: SelectionModel<T>): T[];
+    flattenNodes(structuredData: any[]): T[];
+    nodeDescendents(node: T, nodes: T[], onlyExpandable: boolean): void;
+}
+
+export declare class UniqueSelectionDispatcher implements OnDestroy {
+    listen(listener: UniqueSelectionDispatcherListener): () => void;
+    ngOnDestroy(): void;
+    notify(id: string, name: string): void;
+}
+
+export declare type UniqueSelectionDispatcherListener = (id: string, name: string) => void;