[Flyout System] require title for session flyouts, support custom actions in top menu (#8997)

Co-authored-by: Tomasz Kajtoch <[email protected]>

Author: 2 people

packages/eui/changelogs/upcoming/8897.md

@@ -0,0 +1 @@
+Flyout system menu bar: require tile, support custom actions

packages/eui/src/components/flyout/README.md

@@ -50,12 +50,13 @@ Renders child flyouts within a session:
 - **Width Integration**: Uses main flyout width for positioning
 
 ### `src/components/flyout/manager/flyout_managed.tsx`
-The managed flyout wrapper that integrates with the flyout manager system, handling registration and lifecycle management. Includes size validation for managed flyouts according to business rules.
+The managed flyout wrapper that integrates with the flyout manager system, handling registration and lifecycle management. Includes validation of props for managed flyouts.
 
 ### `src/components/flyout/manager/flyout_validation.ts`
-Validation utilities for flyout size business rules:
+Validation utilities for managed flyout props:
 - **Named Size Validation**: Managed flyouts must use named sizes (s, m, l)
 - **Size Combination Rules**: Parent and child can't both be 'm', parent can't be 'l' with child
+- **Title**: Must be provided either through `flyoutMenuProps` or `aria-label`
 - **Error Handling**: Comprehensive error messages for invalid configurations
 
 ### `src/components/flyout/manager/index.ts`

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

@@ -68,6 +68,7 @@ import {
   isEuiFlyoutSizeNamed,
 } from './const';
 import { useIsPushed } from './hooks';
+import { EuiFlyoutMenu, EuiFlyoutMenuProps } from './flyout_menu';
 import { EuiFlyoutResizeButton } from './_flyout_resize_button';
 import { useEuiFlyoutResizable } from './use_flyout_resizable';
 import {
@@ -198,6 +199,12 @@ interface _EuiFlyoutComponentProps {
    */
   includeSelectorInFocusTrap?: string[] | string;
 
+  /**
+   * Props for the flyout menu to have one rendered in the flyout.
+   * If used, the close button will be automatically hidden, as the flyout menu has its own close button.
+   */
+  flyoutMenuProps?: EuiFlyoutMenuProps;
+
   /**
    * Whether the flyout should be resizable.
    * @default false
@@ -244,6 +251,7 @@ export const EuiFlyoutComponent = forwardRef(
       children,
       as,
       hideCloseButton = false,
+      flyoutMenuProps,
       closeButtonProps,
       closeButtonPosition = 'inside',
       onClose,
@@ -627,14 +635,15 @@ export const EuiFlyoutComponent = forwardRef(
             onAnimationEnd={onAnimationEnd}
           >
             {!isPushed && screenReaderDescription}
-            {!hideCloseButton && (
+            {!flyoutMenuProps && !hideCloseButton && (
               <EuiFlyoutCloseButton
                 {...closeButtonProps}
                 onClose={closeFlyout}
                 closeButtonPosition={closeButtonPosition}
                 side={side}
               />
             )}
+            {flyoutMenuProps && <EuiFlyoutMenu {...flyoutMenuProps} />}
             {resizable && (
               <EuiFlyoutResizeButton
                 type={type}

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

@@ -19,34 +19,36 @@ import { EuiFlyoutMenu, EuiFlyoutMenuProps } from './flyout_menu';
 import { EuiIcon } from '../icon';
 import { EuiPopover } from '../popover';
 import { EuiListGroup, EuiListGroupItem } from '../list_group';
-import { EuiFlyoutMenuContext } from './flyout_menu_context';
 
 interface Args extends EuiFlyoutMenuProps {
   showBackButton: boolean;
-  showCustomAction: boolean;
+  showCustomActions: boolean;
   showPopover: boolean;
 }
 
 const meta: Meta<Args> = {
   title: 'Layout/EuiFlyout/EuiFlyoutMenu',
   component: EuiFlyoutMenu,
   argTypes: {
-    showBackButton: { control: 'boolean' },
-    showCustomAction: { control: 'boolean' },
+    showCustomActions: { control: 'boolean' },
+    customActions: { table: { disable: true } },
     showPopover: { control: 'boolean' },
     backButton: { table: { disable: true } },
+    popover: { table: { disable: true } },
   },
   args: {
+    hideCloseButton: false,
     showBackButton: true,
-    showCustomAction: true,
+    showCustomActions: true,
     showPopover: true,
   },
 };
 
 export default meta;
 
 const MenuBarFlyout = (args: Args) => {
-  const { showCustomAction, showBackButton, showPopover } = args;
+  const { showCustomActions, hideCloseButton, showBackButton, showPopover } =
+    args;
 
   const [isFlyoutOpen, setIsFlyoutOpen] = useState(true);
   const openFlyout = () => setIsFlyoutOpen(true);
@@ -56,6 +58,7 @@ const MenuBarFlyout = (args: Args) => {
 
   /* Back button */
 
+  // TODO: back button should be internalized in EuiFlyoutMenu when historyItems are passed
   const backButton = (
     <EuiButtonEmpty size="xs" color="text">
       <EuiIcon type="editorUndo" /> Back
@@ -75,6 +78,7 @@ const MenuBarFlyout = (args: Args) => {
     { config: { mainTitle: 'Third item' } },
   ];
 
+  // TODO: history popover should be internalized in EuiFlyoutMenu when historyItems are passed
   const historyPopover = (
     <EuiPopover
       button={
@@ -104,13 +108,13 @@ const MenuBarFlyout = (args: Args) => {
     </EuiPopover>
   );
 
-  /* Custom action */
-
-  const handleCustomActionClick = () => {
-    action('custom action clicked')();
-  };
-
-  /* Render */
+  const customActions = ['gear', 'broom'].map((iconType) => ({
+    iconType,
+    onClick: () => {
+      action('custom action')(`${iconType} action clicked`);
+    },
+    'aria-label': `${iconType} action`,
+  }));
 
   return (
     <>
@@ -126,25 +130,14 @@ const MenuBarFlyout = (args: Args) => {
           type="overlay"
           outsideClickCloses={false}
           ownFocus
+          flyoutMenuProps={{
+            title: 'Flyout title',
+            hideCloseButton,
+            backButton: showBackButton ? backButton : undefined,
+            popover: showPopover ? historyPopover : undefined,
+            customActions: showCustomActions ? customActions : undefined,
+          }}
         >
-          <EuiFlyoutMenuContext.Provider value={{ onClose: closeFlyout }}>
-            <EuiFlyoutMenu
-              title="Title"
-              backButton={showBackButton && backButton}
-              popover={showPopover && historyPopover}
-            >
-              {showCustomAction && (
-                <EuiButtonIcon
-                  iconType="gear"
-                  onClick={handleCustomActionClick}
-                  color="text"
-                  size="s"
-                  style={{ blockSize: '20px' }}
-                  aria-label="Custom action"
-                />
-              )}
-            </EuiFlyoutMenu>
-          </EuiFlyoutMenuContext.Provider>
           <EuiFlyoutBody>
             <EuiText>
               <p>Simple flyout content.</p>

packages/eui/src/components/flyout/flyout_menu.styles.ts

@@ -28,5 +28,8 @@ export const euiFlyoutMenuStyles = (euiThemeContext: UseEuiTheme) => {
     euiFlyoutMenu__spacer: css`
       padding-inline: ${euiTheme.size.m};
     `,
+    euiFlyoutMenu__actions: css`
+      block-size: calc(${euiTheme.size.m} * 1.8);
+    `,
   };
 };

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

@@ -9,6 +9,7 @@
 import classNames from 'classnames';
 import React, { FunctionComponent, HTMLAttributes, useContext } from 'react';
 import { useEuiMemoizedStyles, useGeneratedHtmlId } from '../../services';
+import { EuiButtonIcon } from '../button';
 import { CommonProps } from '../common';
 import { EuiFlexGroup, EuiFlexItem } from '../flex';
 import { EuiTitle } from '../title';
@@ -22,15 +23,20 @@ export type EuiFlyoutMenuProps = CommonProps &
     popover?: React.ReactNode;
     title?: React.ReactNode;
     hideCloseButton?: boolean;
+    customActions?: Array<{
+      iconType: string;
+      onClick: () => void;
+      'aria-label': string;
+    }>;
   };
 
 export const EuiFlyoutMenu: FunctionComponent<EuiFlyoutMenuProps> = ({
-  children,
   className,
   backButton,
   popover,
   title,
   hideCloseButton,
+  customActions,
   ...rest
 }) => {
   const { onClose } = useContext(EuiFlyoutMenuContext);
@@ -54,16 +60,13 @@ export const EuiFlyoutMenu: FunctionComponent<EuiFlyoutMenuProps> = ({
     onClose?.(event);
   };
 
-  let closeButton;
-  if (!hideCloseButton) {
-    closeButton = (
-      <EuiFlyoutCloseButton
-        onClose={handleClose}
-        side="right"
-        closeButtonPosition="inside"
-      />
-    );
-  }
+  const closeButton = (
+    <EuiFlyoutCloseButton
+      onClose={handleClose}
+      side="right"
+      closeButtonPosition="inside"
+    />
+  );
 
   return (
     <div className={classes} css={styles.euiFlyoutMenu__container} {...rest}>
@@ -76,11 +79,33 @@ export const EuiFlyoutMenu: FunctionComponent<EuiFlyoutMenuProps> = ({
         {backButton && <EuiFlexItem grow={false}>{backButton}</EuiFlexItem>}
         {popover && <EuiFlexItem grow={false}>{popover}</EuiFlexItem>}
         {titleNode && <EuiFlexItem grow={false}>{titleNode}</EuiFlexItem>}
+
         <EuiFlexItem grow={true}></EuiFlexItem>
-        {children && <EuiFlexItem grow={false}>{children}</EuiFlexItem>}
-        <EuiFlexItem grow={false} css={styles.euiFlyoutMenu__spacer} />
+
+        {customActions &&
+          customActions.map((action, actionIndex) => (
+            <EuiFlexItem
+              grow={false}
+              key={`action-index-flex-item-${actionIndex}`}
+              css={styles.euiFlyoutMenu__actions}
+            >
+              <EuiButtonIcon
+                key={`action-index-icon-${actionIndex}`}
+                aria-label={action['aria-label']}
+                iconType={action.iconType}
+                onClick={action.onClick}
+                color="text"
+                size="s"
+              />
+            </EuiFlexItem>
+          ))}
+
+        {/* spacer to give custom actions room around the close button */}
+        {!hideCloseButton && (
+          <EuiFlexItem grow={false} css={styles.euiFlyoutMenu__spacer} />
+        )}
       </EuiFlexGroup>
-      {closeButton}
+      {!hideCloseButton && closeButton}
     </div>
   );
 };

packages/eui/src/components/flyout/manager/actions.test.ts

@@ -53,53 +53,58 @@ describe('flyout manager actions', () => {
 
   describe('addFlyout', () => {
     it('should create add flyout action with required parameters', () => {
-      const action = addFlyout('flyout-1', LEVEL_MAIN);
+      const action = addFlyout('flyout-1', 'main', LEVEL_MAIN);
 
       expect(action).toEqual({
         type: ACTION_ADD,
         flyoutId: 'flyout-1',
+        title: 'main',
         level: LEVEL_MAIN,
       });
     });
 
     it('should create add flyout action with all parameters', () => {
-      const action = addFlyout('flyout-1', LEVEL_MAIN, 'l');
+      const action = addFlyout('flyout-1', 'main', LEVEL_MAIN, 'l');
 
       expect(action).toEqual({
         type: ACTION_ADD,
         flyoutId: 'flyout-1',
+        title: 'main',
         level: LEVEL_MAIN,
         size: 'l',
       });
     });
 
     it('should default to LEVEL_MAIN when level is not provided', () => {
-      const action = addFlyout('flyout-1');
+      const action = addFlyout('flyout-1', 'flyout title');
 
       expect(action).toEqual({
         type: ACTION_ADD,
         flyoutId: 'flyout-1',
+        title: 'flyout title',
         level: LEVEL_MAIN,
       });
     });
 
     it('should handle child level flyouts', () => {
-      const action = addFlyout('child-1', LEVEL_CHILD, 'm');
+      const action = addFlyout('child-1', 'child', LEVEL_CHILD, 'm');
 
       expect(action).toEqual({
         type: ACTION_ADD,
         flyoutId: 'child-1',
+        title: 'child',
         level: LEVEL_CHILD,
         size: 'm',
       });
     });
 
     it('should handle undefined size parameter', () => {
-      const action = addFlyout('flyout-1', LEVEL_MAIN, undefined);
+      const action = addFlyout('flyout-1', 'main', LEVEL_MAIN, undefined);
 
       expect(action).toEqual({
         type: ACTION_ADD,
         flyoutId: 'flyout-1',
+        title: 'main',
         level: LEVEL_MAIN,
         size: undefined,
       });
@@ -240,7 +245,7 @@ describe('flyout manager actions', () => {
 
   describe('action type safety', () => {
     it('should have correct action type structure', () => {
-      const addAction = addFlyout('test');
+      const addAction = addFlyout('test', 'flyout title');
       const closeAction = closeFlyout('test');
       const setActiveAction = setActiveFlyout('test');
       const setWidthAction = setFlyoutWidth('test', 100);
@@ -256,7 +261,7 @@ describe('flyout manager actions', () => {
     });
 
     it('should maintain action immutability', () => {
-      const action = addFlyout('test', LEVEL_MAIN, 'm');
+      const action = addFlyout('test', 'main', LEVEL_MAIN, 'm');
       const originalAction = { ...action };
 
       // Modify the action object
@@ -269,15 +274,15 @@ describe('flyout manager actions', () => {
 
   describe('edge cases', () => {
     it('should handle empty string flyout IDs', () => {
-      const action = addFlyout('', LEVEL_MAIN);
+      const action = addFlyout('', 'main', LEVEL_MAIN);
       expect(action.flyoutId).toBe('');
     });
 
     it('should handle special characters in flyout IDs', () => {
       const specialIds = ['flyout-1', 'flyout_2', 'flyout.3', 'flyout-4'];
 
       specialIds.forEach((id) => {
-        const action = addFlyout(id, LEVEL_MAIN);
+        const action = addFlyout(id, 'main', LEVEL_MAIN);
         expect(action.flyoutId).toBe(id);
       });
     });