fix(cdk/menu): update docs to reflect current implementation and add

correct role for triggers

Author: mmalerba

src/cdk/menu/menu-trigger.ts

@@ -89,6 +89,7 @@ export class CdkMenuTrigger extends CdkMenuTriggerBase implements OnDestroy {
     @Optional() private readonly _directionality?: Directionality,
   ) {
     super(injector, viewContainerRef, menuStack);
+    this._setRole();
     this._registerCloseHandler();
     this._subscribeToMenuStackClosed();
     this._subscribeToMouseEnter();
@@ -326,4 +327,13 @@ export class CdkMenuTrigger extends CdkMenuTriggerBase implements OnDestroy {
       });
     }
   }
+
+  /** Sets the role attribute for this trigger if needed. */
+  private _setRole() {
+    // If this trigger is part of another menu, the cdkMenuItem directive will handle setting the
+    // role, otherwise this is a standalone trigger, and we should ensure it has role="button".
+    if (!this._parentMenu) {
+      this._elementRef.nativeElement.setAttribute('role', 'button');
+    }
+  }
 }

src/cdk/menu/menu.md

@@ -10,68 +10,65 @@ directives apply their associated ARIA roles to their host element.
 The directives in `@angular/cdk/menu` set the appropriate roles on their host element.
 
 | Directive           | ARIA Role        |
-| ------------------- | ---------------- |
+|---------------------|------------------|
 | CdkMenuBar          | menubar          |
 | CdkMenu             | menu             |
 | CdkMenuGroup        | group            |
 | CdkMenuItem         | menuitem         |
 | CdkMenuItemRadio    | menuitemradio    |
 | CdkMenuItemCheckbox | menuitemcheckbox |
+| CdkMenuTrigger      | button           |
 
 ### Getting started
 
 Import the `CdkMenuModule` into the `NgModule` in which you want to create menus. You can then apply
 menu directives to build your custom menu. A typical menu consists of the following directives:
 
-- `cdkMenuTriggerFor` - links a trigger button to a menu you intend to open
-- `cdkMenuPanel` - wraps the menu and provides a link between the `cdkMenuTriggerFor` and the
-  `cdkMenu`
-- `cdkMenu` - the actual menu you want to open
-- `cdkMenuItem` - added to each button
+- `cdkMenuTriggerFor` - links a trigger element to an `ng-template` containing the menu the trigger opens
+- `cdkMenu` - creates the actual menu content that the trigger will open
+- `cdkMenuItem` - added to each item in the menu
 
 <!-- example({
-  "example": "cdk-menu-standalone-menu",
-  "file": "cdk-menu-standalone-menu-example.html"
+  "example": "cdk-menu-standalone-trigger",
+  "file": "cdk-menu-standalone-trigger-example.html"
   }) -->
 
 Most menu interactions consist of two parts: a trigger and a menu panel.
 
 #### Triggers
 
-You must add the `cdkMenuItem` and `cdkMenuTriggerFor` directives to triggers like so,
+`cdkMenuTriggerFor` can be added to any button to make it a trigger for the given menu, or any menu
+item to make it a trigger for a submenu. When adding this directive, be sure to pass a reference to
+the template containing the menu it should open. You can toggle the associated menu using a mouse
+or keyboard.
 
-```html
-<button cdkMenuItem [cdkMenuTriggerFor]="menu">Click me!</button>
-```
+<!-- example({"example":"cdk-menu-standalone-trigger",
+              "file":"cdk-menu-standalone-trigger-example.html", 
+              "region":"trigger"}) -->
 
-Adding `cdkMenuItem` gives you keyboard navigation and focus management. Associating a trigger with
-a menu is done through the `cdkMenuTriggerFor` directive and you must provide a template reference
-variable to it. Once both of these directives are set, you can toggle the associated menu
-programmatically, using a mouse or using a keyboard.
+When creating a submenu trigger, add both `cdkMenuItem` and `cdkMenuTriggerFor` like so,
 
-#### Menu panels
+<!-- example({"example":"cdk-menu-menubar",
+              "file":"cdk-menu-menubar-example.html", 
+              "region":"file-trigger"}) -->
 
-You must wrap pop-up menus with an `ng-template` with the `cdkMenuPanel` directive and a reference
-variable which must be of type `cdkMenuPanel`. Further, the `cdkMenu` must also reference the
-`cdkMenuPanel`.
+#### Menu content
 
-```html
-<ng-template cdkMenuPanel #panel="cdkMenuPanel">
-  <div cdkMenu [cdkMenuPanel]="panel">
-    <!-- some content -->
-  </div>
-</ng-template>
-```
+Menu content is created using the `cdkMenu` or `cdkMenuBar` components. Menus can be always present
+on the page (referred to as an inline menu), or shown on trigger activation (referred to as a popup
+menu). Popup menus must be wrapped in an `ng-template`, as a reference to the ng-template is needed
+to pass to the trigger directive.
+
+Menus should exclusively contain elements with role `menuitem`, `menuitemcheckbox`,
+`menuitemradio`, or `group`. Supporting directives that automatically apply these roles are
+discussed below.
 
 Note that Angular CDK provides no styles; you must add styles as part of building your custom menu.
 
 ### Menu Bars
 
 The `CdkMenuBar` directive follows the [ARIA menubar][menubar] spec and behaves similar to a desktop
-app menubar. It consists of at least one `CdkMenuItem` which triggers a submenu. A menubar can be
-layed out horizontally or vertically (defaulting to horizontal). If the layout changes, you must set
-the `orientation` attribute to match in order for the keyboard navigation to work properly and for
-menus to open up in the correct location.
+app menubar. It consists of at least one `CdkMenuItem` which triggers a submenu.
 
 <!-- example({
   "example": "cdk-menu-menubar",
@@ -93,22 +90,21 @@ the cursor, similarly to native context menus.
 You can nest context menu container elements. Upon right-click, the menu associated with the closest
 container element will open.
 
-```html
-<div [cdkContextMenuTriggerFor]="outer">
-  My outer context
-  <div [cdkContextMenuTriggerFor]="inner">My inner context</div>
-</div>
-```
+<!-- example({
+  "example": "cdk-menu-nested-context",
+  "file": "cdk-menu-nested-context-example.html",
+  "region": "triggers"
+  }) -->
 
-In the example above, right clicking on "My inner context" will open up the "inner" menu and right
-clicking inside "My outer context" will open up the "outer" menu.
+In the example above, right-clicking on "Inner context menu" will open up the "inner" menu and
+right-clicking inside "Outer context menu" will open up the "outer" menu.
 
 ### Inline Menus
 
 An _inline menu_ is a menu that lives directly on the page rather than a pop-up associated with a
 trigger. You can use an inline menu when you want a persistent menu interaction on a page. Menu
-items within an inline menus are logically grouped together and you can navigate through them using
-your keyboard.
+items within an inline menus are logically grouped together, and you can navigate through them
+using your keyboard.
 
 <!-- example({
   "example": "cdk-menu-inline",
@@ -117,45 +113,47 @@ your keyboard.
 
 ### Menu Items
 
-Both menu and menubar elements should exclusively contain menuitem elements. This directive allows
-the items to be navigated to via keyboard interaction.
+The `cdkMenuItem` directive allows the items to be navigated to via keyboard interaction.
+A menuitem can provide some user defined action by hooking into the `cdkMenuItemTriggered` output.
 
-A menuitem by itself can provide some user defined action by hooking into the `cdkMenuItemTriggered`
-output. An example may be a close button which performs some closing logic.
-
-```html
-<ng-template cdkMenuPanel #panel="cdkMenuPanel">
-  <div cdkMenu [cdkMenuPanel]="panel">
-    <button cdkMenuItem (cdkMenuItemTriggered)="closeApp()">Close</button>
-  </div>
-</ng-template>
-```
+<!-- example({"example":"cdk-menu-standalone-stateful-menu",
+              "file":"cdk-menu-standalone-stateful-menu-example.html", 
+              "region":"reset-item"}) -->
 
 You can create nested menus by using a menuitem as the trigger for another menu.
 
-```html
-<ng-template cdkMenuPanel #panel="cdkMenuPanel">
-  <div cdkMenu [cdkMenuPanel]="panel">
-    <button cdkMenuItem [cdkMenuTriggerFor]="submenu">Open Submenu</button>
-  </div>
-</ng-template>
-```
-
-A menuitem also has two sub-types, neither of which should trigger a menu: CdkMenuItemCheckbox and
-CdkMenuItemRadio
+<!-- example({"example":"cdk-menu-menubar",
+              "file":"cdk-menu-menubar-example.html", 
+              "region":"file-trigger"}) -->
 
 #### Menu Item Checkboxes
 
 A `cdkMenuItemCheckbox` is a special type of menuitem that behaves as a checkbox. You can use this
-type of menuitem to toggle items on and off. An element with the `cdkMenuItemCheckbox` directive
+type of menuitem to toggle items on and off. An element with  `cdkMenuItemCheckbox` directive
 does not need the additional `cdkMenuItem` directive.
 
+Checkbox items do not track their own state. You must bind the checked state using the
+`cdkMenuItemChecked` input and listen to `cdkMenuItemTriggered` to know when it is toggled. If you
+don't bind the state it will reset when the menu is closed and re-opened.
+
+<!-- example({"example":"cdk-menu-standalone-stateful-menu",
+              "file":"cdk-menu-standalone-stateful-menu-example.html", 
+              "region":"bold-item"}) -->
+
 #### Menu Item Radios
 
 A `cdkMenuItemRadio` is a special type of menuitem that behaves as a radio button. You can use this
 type of menuitem for menus with exclusively selectable items. An element with the `cdkMenuItemRadio`
 directive does not need the additional `cdkMenuItem` directive.
 
+As with checkbox items, radio items do not track their own state, but you can track it by binding
+`cdkMenuItemChecked` and listening for `cdkMenuItemTriggered`. If you do not bind the state the
+selection will reset when the menu is closed and reopened.
+
+<!-- example({"example":"cdk-menu-standalone-stateful-menu",
+              "file":"cdk-menu-standalone-stateful-menu-example.html", 
+              "region":"size-items"}) -->
+
 #### Groups
 
 By default `cdkMenu` acts as a group for `cdkMenuItemRadio` elements. Elements with
@@ -165,30 +163,6 @@ can have the checked state.
 If you would like to have unrelated groups of radio buttons within a single menu you should use the
 `cdkMenuGroup` directive.
 
-```html
-<ng-template cdkMenuPanel #panel="cdkMenuPanel">
-  <div cdkMenu [cdkMenuPanel]="panel">
-    <!-- Font size -->
-    <div cdkMenuGroup>
-      <button cdkMenuItemRadio>Small</button>
-      <button cdkMenuItemRadio>Medium</button>
-      <button cdkMenuItemRadio>Large</button>
-    </div>
-    <hr />
-    <!-- Paragraph alignment -->
-    <div cdkMenuGroup>
-      <button cdkMenuItemRadio>Left</button>
-      <button cdkMenuItemRadio>Center</button>
-      <button cdkMenuItemRadio>Right</button>
-    </div>
-  </div>
-</ng-template>
-```
-
-Note however that when the menu is closed and reopened any state is lost. You must subscribe to the
-groups `change` output, or to `cdkMenuItemToggled` on each radio item and track changes your self.
-Finally, you can provide state for each item using the `checked` attribute.
-
 <!-- example({
   "example": "cdk-menu-standalone-stateful-menu",
   "file": "cdk-menu-standalone-stateful-menu-example.html"
@@ -208,8 +182,8 @@ service if it can perform its close actions. In order to determine if the curren
 closed out, the Menu Aim service calculates the slope between a selected target coordinate in the
 submenu and the previous mouse point, and the slope between the target and the current mouse point.
 If the slope of the current mouse point is greater than the slope of the previous that means the
-user is moving towards the submenu and we shouldn't close out. Users however may sometimes stop
-short in a sibling item after moving towards the submenu. The service is intelligent enough the
+user is moving towards the submenu, so we shouldn't close out. Users however may sometimes stop
+short in a sibling item after moving towards the submenu. The service is intelligent enough to
 detect this intention and will trigger the next menu.
 
 ### Accessibility
@@ -227,4 +201,4 @@ Finally, keyboard interaction is supported as defined in the [ARIA menubar keybo
 [keyboard]:
   https://www.w3.org/TR/wai-aria-practices-1.1/#keyboard-interaction-12
   'ARIA Menubar Keyboard Interaction'
-[diagram]: menuaim.png 'Menu Aim Diagram'
+[diagram]: https://material.angular.io/assets/img/menuaim.png 'Menu Aim Diagram'

src/cdk/menu/menuaim.png

@@ -1,5 +1,7 @@
 <div cdkMenuBar>
+  <!-- #docregion file-trigger -->
   <button class="example-menu-bar-item" cdkMenuItem [cdkMenuTriggerFor]="file">File</button>
+  <!-- #enddocregion file-trigger -->
   <button class="example-menu-bar-item" cdkMenuItem [cdkMenuTriggerFor]="edit">Edit</button>
   <button class="example-menu-bar-item" cdkMenuItem [cdkMenuTriggerFor]="format">Format</button>
 </div>
@@ -8,7 +10,7 @@
   <div class="example-menu" cdkMenu>
     <button class="example-menu-item" cdkMenuItem>Share</button>
     <hr />
-    <button class="example-menu-item" cdkMenuItem [cdkMenuTriggerFor]="new">
+    <button class="example-menu-item" cdkMenuItem [cdkMenuTriggerFor]="new_doc">
       New <span>&#10148;</span>
     </button>
     <button class="example-menu-item" cdkMenuItem>Open</button>
@@ -34,19 +36,19 @@
 <ng-template #format >
   <div class="example-menu" cdkMenu>
     <div class="example-menu-group" cdkMenuGroup>
-      <button class="example-menu-item" checked id="bf" cdkMenuItemCheckbox>Bold</button>
-      <button class="example-menu-item" id="if" cdkMenuItemCheckbox>Italic</button>
+      <button cdkMenuItemCheckbox class="example-menu-item" cdkMenuItemChecked>Bold</button>
+      <button cdkMenuItemCheckbox class="example-menu-item">Italic</button>
     </div>
     <hr />
     <div class="example-menu-group" cdkMenuGroup>
-      <button class="example-menu-item" id="small" cdkMenuItemRadio>Small</button>
-      <button class="example-menu-item" checked id="normal" cdkMenuItemRadio>Normal</button>
-      <button class="example-menu-item" id="large" cdkMenuItemRadio>Big</button>
+      <button cdkMenuItemRadio class="example-menu-item">Small</button>
+      <button cdkMenuItemRadio class="example-menu-item" cdkMenuItemChecked>Normal</button>
+      <button cdkMenuItemRadio class="example-menu-item">Big</button>
     </div>
   </div>
 </ng-template>
 
-<ng-template #new>
+<ng-template #new_doc>
   <div class="example-menu" cdkMenu>
     <button class="example-menu-item" cdkMenuItem>Document</button>
     <button class="example-menu-item" cdkMenuItem>From template</button>

src/components-examples/cdk/menu/cdk-menu-menubar/cdk-menu-menubar-example.html

@@ -0,0 +1,43 @@
+.example-context-area {
+  display: inline-grid;
+  border: 2px dashed black;
+}
+
+.example-context-area .example-context-area {
+  margin: 100px;
+  width: 200px;
+  height: 100px;
+}
+
+.example-menu {
+  display: inline-flex;
+  flex-direction: column;
+  min-width: 180px;
+  max-width: 280px;
+  background-color: rgb(255, 255, 255);
+  padding: 6px 0;
+}
+
+.example-menu-item {
+  background-color: transparent;
+  cursor: pointer;
+  border: none;
+
+  user-select: none;
+  min-width: 64px;
+  line-height: 36px;
+  padding: 0 16px;
+
+  display: flex;
+  align-items: center;
+  flex-direction: row;
+  flex: 1;
+}
+
+.example-menu-item:hover {
+  background-color: rgb(208, 208, 208);
+}
+
+.example-menu-item:active {
+  background-color: rgb(170, 170, 170);
+}

src/components-examples/cdk/menu/cdk-menu-nested-context/cdk-menu-nested-context-example.css

@@ -0,0 +1,21 @@
+<!-- #docregion triggers -->
+<div class="example-context-area" [cdkContextMenuTriggerFor]="outer">
+  Outer context menu
+  <div class="example-context-area" [cdkContextMenuTriggerFor]="inner">Inner context menu</div>
+</div>
+<!-- #enddocregion triggers -->
+
+<ng-template #outer>
+  <div class="example-menu" cdkMenu>
+    <button class="example-menu-item" cdkMenuItem>Save</button>
+    <button class="example-menu-item" cdkMenuItem>Exit</button>
+  </div>
+</ng-template>
+
+<ng-template #inner>
+  <div class="example-menu" cdkMenu>
+    <button class="example-menu-item" cdkMenuItem>Cut</button>
+    <button class="example-menu-item" cdkMenuItem>Copy</button>
+    <button class="example-menu-item" cdkMenuItem>Paste</button>
+  </div>
+</ng-template>

src/components-examples/cdk/menu/cdk-menu-nested-context/cdk-menu-nested-context-example.html

@@ -0,0 +1,10 @@
+import {Component} from '@angular/core';
+
+/** @title Nested context menus. */
+@Component({
+  selector: 'cdk-menu-nested-context-example',
+  exportAs: 'cdkMenuNestedContextExample',
+  styleUrls: ['cdk-menu-nested-context-example.css'],
+  templateUrl: 'cdk-menu-nested-context-example.html',
+})
+export class CdkMenuNestedContextExample {}

src/components-examples/cdk/menu/cdk-menu-nested-context/cdk-menu-nested-context-example.ts

@@ -8,7 +8,7 @@
 }
 
 .example-menu-item,
-.example-standalone-item {
+.example-standalone-trigger {
   background-color: transparent;
   cursor: pointer;
   border: none;