feat(cdk-experimental/menu): Add menu skeleton and build scripts

.github/CODEOWNERS

@@ -125,6 +125,7 @@
 /src/cdk-experimental/*                            @jelbourn
 /src/cdk-experimental/column-resize/**             @kseamon @andrewseguin
 /src/cdk-experimental/dialog/**                    @jelbourn @crisbeto
+/src/cdk-experimental/menu/**                      @andy9775
 /src/cdk-experimental/popover-edit/**              @kseamon @andrewseguin
 /src/cdk-experimental/scrolling/**                 @mmalerba
 
@@ -141,6 +142,7 @@
 /src/dev-app/button-toggle/**                      @jelbourn
 /src/dev-app/button/**                             @jelbourn
 /src/dev-app/card/**                               @jelbourn
+/src/dev-app/cdk-experimental-menu/**              @andy9775
 /src/dev-app/checkbox/**                           @jelbourn @devversion
 /src/dev-app/chips/**                              @jelbourn
 /src/dev-app/clipboard/**                          @jelbourn @xkxx

goldens/ts-circular-deps.json

@@ -3,6 +3,11 @@
     "src/cdk-experimental/dialog/dialog-config.ts",
     "src/cdk-experimental/dialog/dialog-container.ts"
   ],
+  [
+    "src/cdk-experimental/menu/menu-item.ts",
+    "src/cdk-experimental/menu/menu-panel.ts",
+    "src/cdk-experimental/menu/menu.ts"
+  ],
   [
     "src/cdk-experimental/popover-edit/edit-event-dispatcher.ts",
     "src/cdk-experimental/popover-edit/edit-ref.ts"

src/cdk-experimental/config.bzl

@@ -2,6 +2,7 @@
 CDK_EXPERIMENTAL_ENTRYPOINTS = [
     "column-resize",
     "dialog",
+    "menu",
     "popover-edit",
     "scrolling",
 ]

src/cdk-experimental/menu/BUILD.bazel

@@ -0,0 +1,16 @@
+load("//tools:defaults.bzl", "ng_module")
+
+package(default_visibility = ["//visibility:public"])
+
+ng_module(
+    name = "menu",
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*.spec.ts"],
+    ),
+    module_name = "@angular/cdk-experimental/menu",
+    deps = [
+        "@npm//@angular/core",
+        "@npm//rxjs",
+    ],
+)

src/cdk-experimental/menu/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export * from './public-api';

src/cdk-experimental/menu/menu-bar.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Directive, Input} from '@angular/core';
+
+/**
+ * Directive applied to an element which configures it as a MenuBar by setting the appropriate
+ * role, aria attributes, and accessable keyboard and mouse handling logic. The component that
+ * this directive is applied to should contain components marked with CdkMenuItem.
+ *
+ */
+@Directive({
+  selector: '[cdkMenuBar]',
+  exportAs: 'cdkMenuBar',
+  host: {
+    'role': 'menubar',
+    '[attr.aria-orientation]': 'orientation',
+  },
+})
+export class CdkMenuBar {
+  /**
+   * Sets the aria-orientation attribute and determines where sub-menus will be opened.
+   * Does not affect styling/layout.
+   */
+  @Input('cdkMenuBarOrientation') orientation: 'horizontal' | 'vertical' = 'horizontal';
+}

src/cdk-experimental/menu/menu-group.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Directive, Output, OnDestroy} from '@angular/core';
+import {Subject} from 'rxjs';
+import {CdkMenuItem} from './menu-item';
+
+/**
+ * Directive which provides grouping logic for CdkMenuItem components marked with role
+ * menuitemradio.
+ * Siblings within the element are part of the same RadioGroup and behave as such.
+ */
+@Directive({
+  selector: '[cdkMenuGroup]',
+  exportAs: 'cdkMenuGroup',
+  host: {
+    'role': 'group',
+  },
+})
+export class CdkMenuGroup implements OnDestroy {
+  /** Emits the element when checkbox or radiobutton state changed  */
+  @Output() change: Subject<CdkMenuItem> = new Subject();
+
+  /** Cleanup event emitters */
+  ngOnDestroy() {
+    this.change.complete();
+  }
+}

src/cdk-experimental/menu/menu-item.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Directive, Output, Input, OnDestroy} from '@angular/core';
+import {Subject} from 'rxjs';
+import {CdkMenuPanel} from './menu-panel';
+
+/**
+ * Directive which provides behavior for an element which when clicked:
+ *  If located in a CdkMenuBar:
+ *    - opens up an attached submenu
+ *
+ *  If located in a CdkMenu/CdkMenuGroup, one of:
+ *    - executes the user defined click handler
+ *    - toggles its checkbox state
+ *    - toggles its radio button state (in relation to siblings)
+ *
+ * If it's in a CdkMenu and it triggers a sub-menu, hovering over the
+ * CdkMenuItem will open the submenu.
+ *
+ */
+@Directive({
+  selector: '[cdkMenuItem], [cdkMenuTriggerFor]',
+  exportAs: 'cdkMenuItem',
+  host: {
+    'type': 'button',
+    '[attr.role]': 'role',
+    '[attr.aria-checked]': '_ariaChecked',
+  },
+})
+export class CdkMenuItem implements OnDestroy {
+  /** Template reference variable to the menu this trigger opens */
+  @Input('cdkMenuTriggerFor') _menuPanel: CdkMenuPanel;
+
+  /** ARIA role for the menu item. */
+  @Input() role: 'menuitem' | 'menuitemradio' | 'menuitemcheckbox' = 'menuitem';
+
+  /** Whether the checkbox or radiobutton is checked */
+  @Input() checked: boolean;
+
+  /** Emits when the attached submenu is opened */
+  @Output() opened: Subject<void> = new Subject();
+
+  /** get the aria-checked value only if element is `menuitemradio` or `menuitemcheckbox` */
+  get _ariaChecked(): boolean | null {
+    if (this.role === 'menuitem') {
+      return null;
+    }
+    return this.checked;
+  }
+
+  /** Whether the menu item opens a menu */
+  opensMenu() {
+    return !!this._menuPanel;
+  }
+
+  /** Cleanup event emitters */
+  ngOnDestroy() {
+    this.opened.complete();
+  }
+}

src/cdk-experimental/menu/menu-module.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {NgModule} from '@angular/core';
+import {CdkMenu} from './menu';
+import {CdkMenuBar} from './menu-bar';
+import {CdkMenuPanel} from './menu-panel';
+import {CdkMenuItem} from './menu-item';
+import {CdkMenuGroup} from './menu-group';
+
+const EXPORTED_DECLARATIONS = [CdkMenuBar, CdkMenu, CdkMenuPanel, CdkMenuItem, CdkMenuGroup];
+@NgModule({
+  exports: EXPORTED_DECLARATIONS,
+  declarations: EXPORTED_DECLARATIONS,
+})
+export class CdkMenuModule {}

src/cdk-experimental/menu/menu-panel.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Directive} from '@angular/core';
+import {CdkMenu} from './menu';
+
+/**
+ * Directive applied to an ng-template which wraps a CdkMenu and provides a reference to the
+ * child element it wraps which allows for opening of the CdkMenu in an overlay.
+ */
+@Directive({selector: 'ng-template[cdkMenuPanel]', exportAs: 'cdkMenuPanel'})
+export class CdkMenuPanel {
+  /** Reference to the child menu component */
+  _menu: CdkMenu;
+}

src/cdk-experimental/menu/menu.md

@@ -0,0 +1,78 @@
+**Warning: this component is still experimental. It may have bugs and the API may change at any
+time**
+
+# Menu
+
+The CDK's `MenuModule` provides a set of directives which allow developers to build custom Menus and
+MenuBars according the the [MenuBar design pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#menu).
+
+## Example
+
+```html
+<ul cdkMenuBar>
+  <li role="none"><button id="file_button" [cdkMenuTriggerFor]="file">File</button></li>
+  <li role="none"><button id="edit_button" [cdkMenuTriggerFor]="edit">Edit</button></li>
+</ul>
+
+<ng-template cdkMenuPanel #file="cdkMenuPanel">
+  <ul cdkMenu id="file_menu">
+    <li role="none"><button id="share_button" cdkMenuItem>Share</button></li>
+    <li role="none"><button id="open_button" cdkMenuItem>Open</button></li>
+    <li role="none"><button id="rename_button" cdkMenuItem>Rename</button></li>
+    <li role="none"><button id="print_button" cdkMenuItem>Print</button></li>
+  </ul>
+</ng-template>
+
+<ng-template cdkMenuPanel #edit="cdkMenuPanel">
+  <ul cdkMenu id="edit_menu">
+    <li role="none"><button id="undo_button" cdkMenuItem>Undo</button></li>
+    <li role="none"><button id="redo_button" cdkMenuItem>Redo</button></li>
+    <li role="none"><button id="cut_button" cdkMenuItem>Cut</button></li>
+    <li role="none"><button id="copy_button" cdkMenuItem>Copy</button></li>
+    <li role="none"><button id="paste_button" cdkMenuItem>Paste</button></li>
+  </ul>
+</ng-template>
+```
+
+## Directives
+
+### cdkMenuBar
+
+`cdkMenuBar` should be applied to one root MenuBar component which contains a set of `cdkMenuItem`
+components. The directive should be applied to a unordered list component. Note that the component is
+always visible and is the main interaction point for the user.
+
+### cdkMenu
+
+`cdkMenu` is applied to the sub-menu component(s) which should be opened by an associated `cdkMenuItem`.
+`cdkMenu` components should not be nested and they should contain `cdkMenuItem` components or
+`cdkMenuGroup` components.
+
+### cdkMenuGroup
+
+`cdkMenuGroup` is used to logically group `cdkMenuItem` components when used with MenuItems which are
+a menuitemradio.
+
+`cdkMenuItem` components marked as `menuitemradio` inside of a `cdkMenuGroup` can only have a single
+active item and follow the RadioButton and RadioGroup standard pattern.
+
+### cdkMenuItem
+
+`cdkMenuItem` is applied to a component and performs one of the following actions based on the set role:
+
+- If menuitem:
+  - triggers a submenu, or
+  - performs some developer provided action
+- If menuitemcheckbox
+  - can be toggled on/off and does not open a submenu
+- If menuitemradio
+  - connected to sibling menuitemradio buttons (group) and does not open a submenu
+
+Further note that menuitemradio and menuitemcheckbox items may be grouped inside of either a `cdkMenu`
+or `cdkMenuGroup` as both directives logically group their children.
+
+### cdkMenuPanel
+
+`cdkMenuPanel` is to be applied to an `ng-template` component. It is used to reference the component it wraps (should contain a single `cdkMenu`) and opens it in an overlay.
+
+`cdkMenuPanel` is a top level element and should not be nested within any of the other directives mentioned here.

src/cdk-experimental/menu/menu.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Directive, Input, Output, OnDestroy} from '@angular/core';
+import {CdkMenuItem} from './menu-item';
+import {Subject} from 'rxjs';
+
+/**
+ * Directive which configures the element as a Menu which should contain child elements marked as
+ * CdkMenuItem or CdkMenuGroup. Sets the appropriate role and aria-attributes for a menu and
+ * contains accessable keyboard and mouse handling logic.
+ *
+ * It also acts as a RadioGroup for elements marked with role `menuitemradio`.
+ */
+@Directive({
+  selector: '[cdkMenu]',
+  exportAs: 'cdkMenu',
+  host: {
+    'role': 'menubar',
+    '[attr.aria-orientation]': 'orientation',
+  },
+})
+export class CdkMenu implements OnDestroy {
+  /**
+   * Sets the aria-orientation attribute and determines where sub-menus will be opened.
+   * Does not affect styling/layout.
+   */
+  @Input('cdkMenuOrientation') orientation: 'horizontal' | 'vertical' = 'vertical';
+
+  /** Event emitted when the menu is closed. */
+  @Output() readonly closed: Subject<void | 'click' | 'tab' | 'escape'> = new Subject();
+
+  /** Emits the activated element when checkbox or radiobutton state changed  */
+  @Output() change: Subject<CdkMenuItem>;
+
+  /** Cleanup event emitters */
+  ngOnDestroy() {
+    this.closed.complete();
+    this.change.complete();
+  }
+}

src/cdk-experimental/menu/public-api.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export * from './menu-module';
+export * from './menu-bar';
+export * from './menu';
+export * from './menu-item';
+export * from './menu-panel';
+export * from './menu-group';

src/dev-app/BUILD.bazel

@@ -23,6 +23,7 @@ ng_module(
         "//src/dev-app/button",
         "//src/dev-app/button-toggle",
         "//src/dev-app/card",
+        "//src/dev-app/cdk-experimental-menu",
         "//src/dev-app/checkbox",
         "//src/dev-app/chips",
         "//src/dev-app/clipboard",