[Flyout System] Improve docs of EuiFlyoutMenu

Author: tsullivan

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

@@ -162,6 +162,15 @@ const HistoryPopover: React.FC<{
   );
 };
 
+/**
+ * The component for the top menu bar inside a flyout. Since this is a private
+ * component, rendering is controlled using the `flyoutMenuProps` prop on
+ * `EuiFlyout`. In managed session flyouts, the Flyout Manager controls a back
+ * button and history popover for navigating to different flyout sessions
+ * within the managed context.
+ *
+ * @private
+ */
 export const EuiFlyoutMenu: FunctionComponent<EuiFlyoutMenuProps> = ({
   titleId,
   className,

packages/website/docs/components/containers/flyout/index.mdx

@@ -1023,17 +1023,31 @@ import { EuiBetaBadge } from '@elastic/eui';
 This component is still in beta and may change in the future.
 :::
 
+`EuiFlyoutMenu` is the top menu bar of a flyout. It is a private component, and is controlled by the `flyoutMenuProps` prop of `EuiFlyout`.
+
 ```tsx
-<EuiFlyout>
-  <EuiFlyoutMenu>
-    Hi mom
-  </EuiFlyoutMenu>
-  <EuiFlyoutHeader>Parent header</EuiFlyoutHeader>
-  <EuiFlyoutBody>Parent body</EuiFlyoutBody>
-  <EuiFlyoutFooter>Parent footer</EuiFlyoutFooter>
+<EuiFlyout
+  onClose={() => {}}
+  flyoutMenuProps={{
+    title: 'My flyout',
+    customActions: [
+      {
+        iconType: 'gear',
+        ['aria-label']: 'Settings',
+        onClick: () => {
+          console.log('Settings clicked');
+        },
+      },
+    ],
+  }}
+>
+  <EuiFlyoutBody>Flyout body</EuiFlyoutBody>
+  <EuiFlyoutFooter>Flyout footer</EuiFlyoutFooter>
 </EuiFlyout>
 ```
 
+In [managed session flyouts]('./session-management.mdx'), the Flyout Manager controls a back button and a history popover control for navigating to different flyout sessions within the managed context.
+
 ## Props
 
 import docgen from '@elastic/eui-docgen/dist/components/flyout';

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

@@ -117,14 +117,29 @@ session as the main flyout - you can set `session="inherit"` or omit the `sessio
 as "inherit" is the default behavior.
 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 of the system. Use the `title`
+field of the `flyoutMenuProps` to set the title of the flyout.
+
 ```tsx
 {/* Render a new main flyout and create a flyout session */}
-<EuiFlyout session="start">
+<EuiFlyout
+  session="start"
+  flyoutMenuProps={{
+    title: 'My main flyout'
+  }}
+>
   <EuiFlyoutBody>
     I'm the main flyout
   </EuiFlyoutBody>
   {/* Render a new child flyout - notice the lack of the `session` prop */}
-  <EuiFlyout>
+  <EuiFlyout
+    flyoutMenuProps={{
+      title: 'My child flyout'
+    }}
+  >
     I'm the child flyout that belongs to the same session as the main flyout
   </EuiFlyout>
 </EuiFlyout>
@@ -136,7 +151,12 @@ can set `session="never"` which will render it as a regular unmanaged flyout.
 ```tsx
 <>
   {/* Render a new main flyout and create a flyout session */}
-  <EuiFlyout session="start">
+  <EuiFlyout
+    session="start"
+    flyoutMenuProps={{
+      title: 'My flyout in a session'
+    }}
+  >
     <EuiFlyoutBody>
       I'm the main flyout in a session
     </EuiFlyoutBody>