Update docs

Author: tsullivan

packages/eui/src/components/flyout/flyout_menu.tsx

@@ -47,7 +47,7 @@ export interface EuiFlyoutHistoryItem {
 }
 
 /**
- * Custom action item for the flyout menu header
+ * Custom action item for the flyout menu component
  */
 export interface EuiFlyoutMenuCustomAction {
   /**
@@ -75,32 +75,29 @@ export type EuiFlyoutMenuProps = CommonProps &
      * ```jsx
      * <EuiFlyout
      *   aria-labelledby="myMenuTitleId"
+     *   flyoutMenuProps={{ title: 'Menu title', titleId: 'myMenuTitleId' }
      * >
-     *   <EuiFlyoutMenu
-     *     titleId="myMenuTitleId"
-     *     title="Menu title"
-     *   />
+     *  ...
      * </EuiFlyout>
      * ```
      */
     titleId?: string;
     /**
-     * Title for the menu header
+     * Title for the menu component. In a managed flyout context, the title is used to indicate the flyout session for history navigation.
      */
     title?: React.ReactNode;
     /**
-     * Hides the title in the flyout menu bar.
-     * If the flyout is used in a managed flyout session as a "main" flyout, the default will be true, as main flyouts typically show a title in an EuiFlyoutHeader instead.
-     * @default true for main flyout in managed flyout session; false otherwise
+     * Hides the title in the `EuiFlyoutMenu`. This is useful when the title is already shown in an `EuiFlyoutHeader`.
+     * @default true for main flyout in a managed flyout session; false otherwise
      */
     hideTitle?: boolean;
     /**
-     * Hides the close button in the menu header
+     * Hides the close button in the menu component
      * @default false
      */
     hideCloseButton?: boolean;
     /**
-     * Shows a back button in the menu header
+     * Shows a back button in the menu component
      * @default false
      */
     showBackButton?: boolean;
@@ -113,7 +110,7 @@ export type EuiFlyoutMenuProps = CommonProps &
      */
     historyItems?: EuiFlyoutHistoryItem[];
     /**
-     * List of custom action items for the menu header
+     * List of custom action items for the menu component
      */
     customActions?: EuiFlyoutMenuCustomAction[];
   };

packages/website/docs/components/containers/flyout/session-management.mdx

@@ -39,12 +39,17 @@ export default () => {
         <EuiFlyout
           session="start"
           size="s"
-          aria-label="Flyout A - main"
-          flyoutMenuProps={{
-            title: 'Welcome to the flyout session management journey!',
-          }}
+          aria-labelledby="welcomeHeading"
+          flyoutMenuProps={{ title: 'Welcome' }}
           onClose={() => setIsOpenFlyoutA(false)}
         >
+          <EuiFlyoutHeader>
+            <EuiTitle>
+              <h2 id="welcomeHeading">
+                Welcome to the flyout session management journey!
+              </h2>
+            </EuiTitle>
+          </EuiFlyoutHeader>
           <EuiFlyoutBody>
             <EuiText>This flyout is rendered with the <EuiCode>{'session="start"'}</EuiCode> prop set which creates a new flyout session and marks this flyout as main.</EuiText>
             <EuiSpacer />
@@ -60,12 +65,17 @@ export default () => {
         <EuiFlyout
           session="start"
           size="m"
-          aria-label="Flyout B - main"
-          flyoutMenuProps={{
-            title: <>Glad to meet you, {name || 'stranger'}!</>,
-          }}
+          aria-labelledby="flyoutBHeading"
+          flyoutMenuProps={{ title: 'Flyout B' }}
           onClose={() => setIsOpenFlyoutB(false)}
         >
+          <EuiFlyoutHeader>
+            <EuiTitle>
+              <h2 id="flyoutBHeading">
+                Glad to meet you, {name || 'stranger'}!
+              </h2>
+            </EuiTitle>
+          </EuiFlyoutHeader>
           <EuiFlyoutBody>
             <EuiText>
               This flyout is also rendered with the <EuiCode>{'session="start"'}</EuiCode> prop added which creates a <strong>second flyout session</strong> and marks this flyout as main in that session.
@@ -119,9 +129,19 @@ All bindings and configuration will be handled automatically.
 
 ### Session title
 
-Flyout sessions within the managed system require a title that can be
-referenced in the history navigation features. Use the `title`
-field of the `flyoutMenuProps` to set the title of the flyout.
+Managed flyout sessions require a title that can be referenced in the history
+navigation features. Use the `title` field of the `flyoutMenuProps` to set the
+title of the flyout session. If `flyoutMenuProps` is omitted or a `title` field
+is not given in `flyoutMenuProps`, the manager will use the `aria-label`
+attribute of `EuiFlyout` as the source for the session's title. If no source
+for a title is given, a default title will be provided.
+
+:::info Note
+The "main" flyout in a session should use `EuiFlyoutHeader` for the actual
+flyout heading. For this reason, the `title` given from `flyoutMenuProps` will
+not be visible to end users. However, a title is still needed for the history
+navigation feature of the flyout session management system.
+:::
 
 ```tsx
 {/* Render a new main flyout and create a flyout session */}
@@ -130,17 +150,28 @@ field of the `flyoutMenuProps` to set the title of the flyout.
   flyoutMenuProps={{
     title: 'My main flyout'
   }}
+  aria-labelledby="myFlyoutHeading"
 >
+  <EuiFlyoutHeader>
+    <EuiTitle>
+      <h2 id="myFlyoutHeading">
+        I'm the main flyout heading
+      </h2>
+    </EuiTitle>
+  </EuiFlyoutHeader>
   <EuiFlyoutBody>
-    I'm the main flyout
+    I'm the main flyout body
   </EuiFlyoutBody>
   {/* Render a new child flyout - notice the lack of the `session` prop */}
   <EuiFlyout
     flyoutMenuProps={{
       title: 'My child flyout'
     }}
   >
-    I'm the child flyout that belongs to the same session as the main flyout
+    {/* Render a child flyout contents. Notice the lack of the EuiFlyoutHeader component - the child flyout menu shows the title from flyoutMenuProps */}
+    <EuiFlyoutBody>
+      I'm the child flyout that belongs to the same session as the main flyout
+    </EuiFlyoutBody>
   </EuiFlyout>
 </EuiFlyout>
 ```