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

andy9775 · web-flow · commit c7cadc35d369 · 2020-06-12T10:11:54.000-07:00
* feat(cdk-experimental/menu): Add menu skeleton and build scripts Configure bazel scripts for a cdk menu feature along with the general structure identifying the set of directives which make it up * feat(cdk-experimental/menu): Configure dev-app Configure dev-app for cdk-experimental/menu * build: Allow indirect circular dependency between menu and menu-item A CdkMenuItem opens a CdkMenuPanel and therefore must reference it. A CdkMenuPanel contains a CdkMenu and therefore must reference it. A CdkMenu contains CdkMenuItem's and therefore must reference it. * feat(cdk-experimental/menu): Quote all host keys * feat(cdk-experimental/menu): Add missing aria-attributes * feat(cdk-experimental/menu): Clear up CdkMenuItem comment * feat(cdk-experimental/menu): Remove unused build dep * feat(cdk-experimental/menu): Fix codeowners Move from material-experimental section to cdk-experimental * feat(cdk-experimental/menu): Grammer fix * feat(cdk-experimental/menu): explicitly specify the return when null and boolean * feat(cdk-experimental/menu): Clear up documentation/comments * feat(cdk-experimental/menu): Make cdkMenuOrientation comment more clear * feat(cdk-experimental/menu): Make orientation attribute public for consistency * feat(cdk-experimental/menu): Remove unnecessary comment for role binding * feat(cdk-experimental/menu): Fix orientation attribute on host binding typo * feat(cdk-experimental/menu): Refactor `orientation` property comment for clarity * feat(cdk-experimental/menu): Refactor event emitter types Emitters self complete when used with @output * feat(cdk-experimental/menu): Remove documentation to be added once feature is complete * feat(cdk-experimental/menu): Rename opensMenu method hasSubmenu specifies that it refers to the menu it opens and not its parent * feat(cdk-experimental/menu): Use getter function not property for aria-checked Getter property generates more code than a getter function - prefer to use a function. * feat(cdk-experimental/menu): refactor MenuGroup doc for clarity * feat(cdk-experimental/menu): add @jelbourn to CODEOWNERS for cdk-experimental/menu * feat(cdk-experimental/menu): coerce MenuItem checked state to boolean * feat(cdk-experimental/menu): nit: rename val to value
diff --git a/.github/CODEOWNERS b/.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/**                      @jelbourn @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/**              @jelbourn @andy9775
 /src/dev-app/checkbox/**                           @jelbourn @devversion
 /src/dev-app/chips/**                              @jelbourn
 /src/dev-app/clipboard/**                          @jelbourn @xkxx
diff --git a/goldens/ts-circular-deps.json b/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"
diff --git a/src/cdk-experimental/config.bzl b/src/cdk-experimental/config.bzl
@@ -2,6 +2,7 @@
 CDK_EXPERIMENTAL_ENTRYPOINTS = [
     "column-resize",
     "dialog",
+    "menu",
     "popover-edit",
     "scrolling",
 ]
diff --git a/src/cdk-experimental/menu/BUILD.bazel b/src/cdk-experimental/menu/BUILD.bazel
@@ -0,0 +1,17 @@
+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 = [
+        "//src/cdk/coercion",
+        "@npm//@angular/core",
+        "@npm//rxjs",
+    ],
+)
diff --git a/src/cdk-experimental/menu/index.ts b/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';
diff --git a/src/cdk-experimental/menu/menu-bar.ts b/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';
+}
diff --git a/src/cdk-experimental/menu/menu-group.ts b/src/cdk-experimental/menu/menu-group.ts
@@ -0,0 +1,26 @@
+/**
+ * @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, EventEmitter} from '@angular/core';
+import {CdkMenuItem} from './menu-item';
+
+/**
+ * Directive which acts as a grouping container for `CdkMenuItem` instances with
+ * `role="menuitemradio"`, similar to a `role="radiogroup"` element.
+ */
+@Directive({
+  selector: '[cdkMenuGroup]',
+  exportAs: 'cdkMenuGroup',
+  host: {
+    'role': 'group',
+  },
+})
+export class CdkMenuGroup {
+  /** Emits the element when checkbox or radiobutton state changed  */
+  @Output() change: EventEmitter<CdkMenuItem> = new EventEmitter();
+}
diff --git a/src/cdk-experimental/menu/menu-item.ts b/src/cdk-experimental/menu/menu-item.ts
@@ -0,0 +1,70 @@
+/**
+ * @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, EventEmitter} from '@angular/core';
+import {CdkMenuPanel} from './menu-panel';
+import {coerceBooleanProperty, BooleanInput} from '@angular/cdk/coercion';
+
+/**
+ * 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]': '_getAriaChecked()',
+  },
+})
+export class CdkMenuItem {
+  /** 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()
+  get checked() {
+    return this._checked;
+  }
+  set checked(value: boolean) {
+    this._checked = coerceBooleanProperty(value);
+  }
+  private _checked = false;
+
+  /** Emits when the attached submenu is opened */
+  @Output() opened: EventEmitter<void> = new EventEmitter();
+
+  /** get the aria-checked value only if element is `menuitemradio` or `menuitemcheckbox` */
+  _getAriaChecked(): boolean | null {
+    if (this.role === 'menuitem') {
+      return null;
+    }
+    return this.checked;
+  }
+
+  /** Whether the menu item opens a menu */
+  hasSubmenu() {
+    return !!this._menuPanel;
+  }
+
+  static ngAcceptInputType_checked: BooleanInput;
+}
diff --git a/src/cdk-experimental/menu/menu-module.ts b/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 {}
diff --git a/src/cdk-experimental/menu/menu-panel.ts b/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;
+}
diff --git a/src/cdk-experimental/menu/menu.ts b/src/cdk-experimental/menu/menu.ts
@@ -0,0 +1,39 @@
+/**
+ * @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, EventEmitter} from '@angular/core';
+import {CdkMenuItem} from './menu-item';
+
+/**
+ * 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 {
+  /**
+   * 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: EventEmitter<void | 'click' | 'tab' | 'escape'> = new EventEmitter();
+
+  /** Emits the activated element when checkbox or radiobutton state changed  */
+  @Output() change: EventEmitter<CdkMenuItem>;
+}
diff --git a/src/cdk-experimental/menu/public-api.ts b/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';
diff --git a/src/dev-app/BUILD.bazel b/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",
diff --git a/src/dev-app/cdk-experimental-menu/BUILD.bazel b/src/dev-app/cdk-experimental-menu/BUILD.bazel
@@ -0,0 +1,16 @@
+load("//tools:defaults.bzl", "ng_module")
+
+package(default_visibility = ["//visibility:public"])
+
+ng_module(
+    name = "cdk-experimental-menu",
+    srcs = glob(["**/*.ts"]),
+    assets = [
+        "cdk-menu-demo.html",
+        "cdk-menu-demo.css",
+    ],
+    deps = [
+        "//src/cdk-experimental/menu",
+        "@npm//@angular/router",
+    ],
+)
diff --git a/src/dev-app/cdk-experimental-menu/cdk-menu-demo-module.ts b/src/dev-app/cdk-experimental-menu/cdk-menu-demo-module.ts
@@ -0,0 +1,24 @@
+/**
+ * @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 {CommonModule} from '@angular/common';
+import {RouterModule} from '@angular/router';
+import {CdkMenuModule} from '@angular/cdk-experimental/menu';
+
+import {CdkMenuDemo} from './cdk-menu-demo';
+
+@NgModule({
+  imports: [
+    CdkMenuModule,
+    CommonModule,
+    RouterModule.forChild([{path: '', component: CdkMenuDemo}]),
+  ],
+  declarations: [CdkMenuDemo],
+})
+export class CdkMenuDemoModule {}
diff --git a/src/dev-app/cdk-experimental-menu/cdk-menu-demo.css b/src/dev-app/cdk-experimental-menu/cdk-menu-demo.css
@@ -0,0 +1,5 @@
+.example-menu-bar {
+  display: flex;
+  flex-direction: row;
+  list-style: none;
+}
diff --git a/src/dev-app/cdk-experimental-menu/cdk-menu-demo.html b/src/dev-app/cdk-experimental-menu/cdk-menu-demo.html
@@ -0,0 +1,23 @@
+<ul cdkMenuBar class="example-menu-bar">
+  <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>
diff --git a/src/dev-app/cdk-experimental-menu/cdk-menu-demo.ts b/src/dev-app/cdk-experimental-menu/cdk-menu-demo.ts
@@ -0,0 +1,15 @@
+/**
+ * @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 {Component} from '@angular/core';
+
+@Component({
+  templateUrl: 'cdk-menu-demo.html',
+  styleUrls: ['cdk-menu-demo.css'],
+})
+export class CdkMenuDemo {}
diff --git a/src/dev-app/dev-app/dev-app-layout.ts b/src/dev-app/dev-app/dev-app-layout.ts
@@ -29,6 +29,7 @@ export class DevAppLayout {
     {name: 'Button Toggle', route: '/button-toggle'},
     {name: 'Button', route: '/button'},
     {name: 'Card', route: '/card'},
+    {name: 'Cdk Experimental Menu', route: '/cdk-experimental-menu'},
     {name: 'Checkbox', route: '/checkbox'},
     {name: 'Chips', route: '/chips'},
     {name: 'Clipboard', route: '/clipboard'},
diff --git a/src/dev-app/dev-app/routes.ts b/src/dev-app/dev-app/routes.ts

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`	`CDK_EXPERIMENTAL_ENTRYPOINTS = [`
`3`	`3`	`"column-resize",`
`4`	`4`	`"dialog",`
	`5`	`+ "menu",`
`5`	`6`	`"popover-edit",`
`6`	`7`	`"scrolling",`
`7`	`8`	`]`