add category option for context menus (#4144)

* enhance grouping for context menu options

Signed-off-by: David Sinclair <david@sinclair.tech>

* change log

Signed-off-by: David Sinclair <david@sinclair.tech>

* remove type export

Signed-off-by: David Sinclair <david@sinclair.tech>

* revert border and prevent destroy options

Signed-off-by: David Sinclair <david@sinclair.tech>

* update comments for building panels

Signed-off-by: David Sinclair <dsincla@rei.com>

* build panels tests and more comments

Signed-off-by: David Sinclair <dsincla@rei.com>

* add category option for context menus

Signed-off-by: David Sinclair <dsincla@rei.com>

* changelog

Signed-off-by: David Sinclair <dsincla@rei.com>

* add order to groups

Signed-off-by: David Sinclair <dsincla@rei.com>

* documentation, shorter copyrighty, minor cleanup

Signed-off-by: David Sinclair <dsincla@rei.com>

* changelog

Signed-off-by: David Sinclair <dsincla@rei.com>

---------

Signed-off-by: David Sinclair <david@sinclair.tech>
Signed-off-by: David Sinclair <dsincla@rei.com>
Signed-off-by: Ashish Agrawal <ashish81394@gmail.com>
Co-authored-by: Ashish Agrawal <ashish81394@gmail.com>
(cherry picked from commit cb27336)
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

# Conflicts:
#	CHANGELOG.md

examples/ui_actions_explorer/public/context_menu_examples/context_menu_examples.tsx

@@ -36,6 +36,7 @@ import { PanelViewWithSharingLong } from './panel_view_with_sharing_long';
 import { PanelEdit } from './panel_edit';
 import { PanelEditWithDrilldowns } from './panel_edit_with_drilldowns';
 import { PanelEditWithDrilldownsAndContextActions } from './panel_edit_with_drilldowns_and_context_actions';
+import { PanelGroupOptionsAndContextActions } from './panel_group_options_and_context_actions';
 
 export const ContextMenuExamples: React.FC = () => {
  return (
@@ -59,7 +60,6 @@ export const ContextMenuExamples: React.FC = () => {
  <PanelViewWithSharingLong />
  </EuiFlexItem>
  </EuiFlexGroup>
-
  <EuiFlexGroup>
  <EuiFlexItem>
  <PanelEdit />
@@ -71,6 +71,11 @@ export const ContextMenuExamples: React.FC = () => {
  <PanelEditWithDrilldownsAndContextActions />
  </EuiFlexItem>
  </EuiFlexGroup>
+ <EuiFlexGroup>
+ <EuiFlexItem>
+ <PanelGroupOptionsAndContextActions />
+ </EuiFlexItem>
+ </EuiFlexGroup>
  </EuiText>
  );
 };

examples/ui_actions_explorer/public/context_menu_examples/panel_group_options_and_context_actions.tsx

@@ -0,0 +1,83 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as React from 'react';
+import { EuiButton, EuiContextMenu, EuiPopover } from '@elastic/eui';
+import useAsync from 'react-use/lib/useAsync';
+import { buildContextMenuForActions, Action } from '../../../../src/plugins/ui_actions/public';
+import { sampleAction } from './util';
+
+export const PanelGroupOptionsAndContextActions: React.FC = () => {
+ const [open, setOpen] = React.useState(false);
+
+ const context = {};
+ const trigger: any = 'TEST_TRIGGER';
+ const drilldownGrouping: Action['grouping'] = [
+ {
+ id: 'drilldowns',
+ getDisplayName: () => 'Uncategorized group',
+ getIconType: () => 'popout',
+ order: 20,
+ },
+ ];
+ const exampleGroup: Action['grouping'] = [
+ {
+ id: 'example',
+ getDisplayName: () => 'Example group',
+ getIconType: () => 'cloudStormy',
+ order: 20,
+ category: 'visAug',
+ },
+ ];
+ const alertingGroup: Action['grouping'] = [
+ {
+ id: 'alerting',
+ getDisplayName: () => 'Alerting',
+ getIconType: () => 'cloudStormy',
+ order: 20,
+ category: 'visAug',
+ },
+ ];
+ const anomaliesGroup: Action['grouping'] = [
+ {
+ id: 'anomalies',
+ getDisplayName: () => 'Anomalies',
+ getIconType: () => 'cloudStormy',
+ order: 30,
+ category: 'visAug',
+ },
+ ];
+ const actions = [
+ sampleAction('test-1', 100, 'Edit visualization', 'pencil'),
+ sampleAction('test-2', 99, 'Clone panel', 'partial'),
+
+ sampleAction('test-9', 10, 'Create drilldown', 'plusInCircle', drilldownGrouping),
+ sampleAction('test-10', 9, 'Manage drilldowns', 'list', drilldownGrouping),
+
+ sampleAction('test-11', 10, 'Example action', 'dashboardApp', exampleGroup),
+ sampleAction('test-11', 10, 'Alertin action 1', 'dashboardApp', alertingGroup),
+ sampleAction('test-12', 9, 'Alertin action 2', 'dashboardApp', alertingGroup),
+ sampleAction('test-13', 8, 'Anomalies 1', 'cloudStormy', anomaliesGroup),
+ sampleAction('test-14', 7, 'Anomalies 2', 'link', anomaliesGroup),
+ ];
+
+ const panels = useAsync(() =>
+ buildContextMenuForActions({
+ actions: actions.map((action) => ({ action, context, trigger })),
+ })
+ );
+
+ return (
+ <EuiPopover
+ button={<EuiButton onClick={() => setOpen((x) => !x)}>Grouping with categories</EuiButton>}
+ isOpen={open}
+ panelPaddingSize="none"
+ anchorPosition="downLeft"
+ closePopover={() => setOpen(false)}
+ >
+ <EuiContextMenu initialPanelId={'mainMenu'} panels={panels.value} />
+ </EuiPopover>
+ );
+};

src/plugins/ui_actions/README.md

@@ -97,3 +97,12 @@ Use the UI actions explorer in the Developer examples to learn more about the se
 ```sh
 yarn start --run-examples
 ```
+
+## Action Properties
+
+Refer to [./public/actions/action.ts](./public/actions/action.ts) for all properties, keeping in mind it extends the [presentable](./public/util/presentable.ts) interface. Here are some properties that provide special functionality and customization.
+
+- `order` is used when there is more than one action matched to a trigger and within context menus. Higher numbers are displayed first.
+- `getDisplayName` is a function that can return either a string or a JSX element. Returning a JSX element allows flexibility with formatting.
+- `getIconType` can be used to add an icon before the display name.
+- `grouping` determines where this item should appear as a submenu. Each group can also contain a category, which is used within context menus to organize similar groups into the same section of the menu. See examples explorer for more details about what this looks like within a context menu.

src/plugins/ui_actions/public/context_menu/build_eui_context_menu_panels.test.ts

@@ -448,3 +448,123 @@ test('groups with deep nesting', async () => {
  ]
  `);
 });
+
+// Tests with:
+// a regular action
+// a group with 2 actions uncategorized
+// a group with 2 actions with a category of "test-category" and low order of 10
+// a group with 1 actions with a category of "test-category" and high order of 20
+test('groups with categories and order', async () => {
+ const grouping1 = [
+ {
+ id: 'test-group',
+ getDisplayName: () => 'Test group',
+ getIconType: () => 'bell',
+ },
+ ];
+ const grouping2 = [
+ {
+ id: 'test-group-2',
+ getDisplayName: () => 'Test group 2',
+ getIconType: () => 'bell',
+ category: 'test-category',
+ order: 10,
+ },
+ ];
+ const grouping3 = [
+ {
+ id: 'test-group-3',
+ getDisplayName: () => 'Test group 3',
+ getIconType: () => 'bell',
+ category: 'test-category',
+ order: 20,
+ },
+ ];
+
+ const actions = [
+ createTestAction({
+ dispayName: 'Foo 1',
+ }),
+ createTestAction({
+ dispayName: 'Bar 1',
+ grouping: grouping1,
+ }),
+ createTestAction({
+ dispayName: 'Bar 2',
+ grouping: grouping1,
+ }),
+ createTestAction({
+ dispayName: 'Qux 1',
+ grouping: grouping2,
+ }),
+ createTestAction({
+ dispayName: 'Qux 2',
+ grouping: grouping2,
+ }),
+ // It is expected that, because there is only 1 action within this group,
+ // it will be added to the mainMenu as a single item, but next to other
+ // groups of the same category. When a group has a category, but only one
+ // item, we just add that single item; otherwise, we add a link to the group
+ createTestAction({
+ dispayName: 'Waldo 1',
+ grouping: grouping3,
+ }),
+ ];
+ const menu = await buildContextMenuForActions({
+ actions: actions.map((action) => ({ action, context: {}, trigger: 'TEST' as any })),
+ });
+
+ expect(menu.map(resultMapper)).toMatchInlineSnapshot(`
+ Array [
+ Object {
+ "items": Array [
+ Object {
+ "name": "Foo 1",
+ },
+ Object {
+ "isSeparator": true,
+ },
+ Object {
+ "name": "Test group",
+ },
+ Object {
+ "isSeparator": true,
+ },
+ Object {
+ "name": "Waldo 1",
+ },
+ Object {
+ "name": "Test group 2",
+ },
+ ],
+ },
+ Object {
+ "items": Array [
+ Object {
+ "name": "Bar 1",
+ },
+ Object {
+ "name": "Bar 2",
+ },
+ ],
+ },
+ Object {
+ "items": Array [
+ Object {
+ "name": "Qux 1",
+ },
+ Object {
+ "name": "Qux 2",
+ },
+ ],
+ },
+ Object {
+ "items": Array [
+ Object {
+ "name": "Waldo 1",
+ },
+ ],
+ },
+ ]
+ `);
+});

src/plugins/ui_actions/public/context_menu/build_eui_context_menu_panels.tsx

@@ -64,6 +64,8 @@ type PanelDescriptor = EuiContextMenuPanelDescriptor & {
  _level?: number;
  _icon?: string;
  items: ItemDescriptor[];
+ _category?: string;
+ _order?: number;
 };
 
 const onClick = (action: Action, context: ActionExecutionContext<object>, close: () => void) => (
@@ -125,7 +127,7 @@ const removeItemMetaFields = (items: ItemDescriptor[]): EuiContextMenuPanelItemD
 const removePanelMetaFields = (panels: PanelDescriptor[]): EuiContextMenuPanelDescriptor[] => {
  const euiPanels: EuiContextMenuPanelDescriptor[] = [];
  for (const panel of panels) {
- const { _level: omit, _icon: omit2, ...rest } = panel;
+ const { _level: omit, _icon: omit2, _category: omit3, _order: omit4, ...rest } = panel;
  euiPanels.push({ ...rest, items: removeItemMetaFields(rest.items) });
  }
  return euiPanels;
@@ -179,6 +181,8 @@ export async function buildContextMenuForActions({
  items: [],
  _level: i,
  _icon: group.getIconType ? group.getIconType(context) : 'empty',
+ _category: group.category,
+ _order: group.order,
  };
 
  // If there are multiple groups and this is not the first group,
@@ -231,17 +235,57 @@ export async function buildContextMenuForActions({
  // Any additional items are hidden behind a "more" item
  wrapMainPanelItemsIntoSubmenu(panels, 'mainMenu');
 
+ // This will be used to store items that eventually are placed into the
+ // mainMenu panel. Specifying a category allows for placing groups into the
+ // mainMenu so they appear without the separator between them.
+ const categories = {};
+
  for (const panel of Object.values(panels)) {
- // If the panel is a root-level panel, such as the parent of a group,
- // then create mainMenu item for this panel
- if (panel._level === 0) {
+ // Do nothing if not root-level panel, such as the parent of a group
+ if (panel._level !== 0) {
+ continue;
+ }
+
+ // Proceed to create mainMenu item for this panel
+
+ // If a category is specified, store either a link to the panel or the
+ // item within to that category. We will deal with the category after
+ // looping through all panels.
+ if (panel._category) {
+ // Create array to store category items
+ if (!categories[panel._category]) {
+ categories[panel._category] = [];
+ }
+
+ // If multiple items in the panel, store a link to this panel into the category.
+ // Otherwise, just store the single item into the category.
+ if (panel.items.length > 1) {
+ categories[panel._category].push({
+ order: panel._order,
+ items: [
+ {
+ name: panel.title || panel.id,
+ icon: panel._icon || 'empty',
+ panel: panel.id,
+ },
+ ],
+ });
+ } else {
+ categories[panel._category].push({
+ order: panel._order || 0,
+ items: panel.items,
+ });
+ }
+ } else {
+ // If no category, continue with adding items to the mainMenu
+
  // Add separator with unique key if needed
  if (panels.mainMenu.items.length) {
  panels.mainMenu.items.push({ isSeparator: true, key: `${panel.id}separator` });
  }
 
  // If a panel has more than one child, then allow items to be grouped
- // and link to it in the mainMenu. Otherwise, flatten the group.
+ // and link to it in the mainMenu. Otherwise, link to the single item.
  // Note: this only happens on the root level panels, not for inner groups.
  if (panel.items.length > 1) {
  panels.mainMenu.items.push({
@@ -255,6 +299,27 @@ export async function buildContextMenuForActions({
  }
  }
 
+ // For each category, add a separator before each one and then add category items.
+ // This is for the mainMenu panel.
+ Object.keys(categories).forEach((key) => {
+ // Get the items sorted by group order, allowing for groups within categories
+ // to be ordered. A category consists of an order and its items.
+ // Higher orders are sorted to the top.
+ const sortedEntries = categories[key].sort((a, b) => b.order - a.order);
+ const sortedItems = sortedEntries.reduce(
+ (items, category) => [...items, ...category.items],
+ []
+ );
+
+ // Add separator with unique key if needed
+ if (panels.mainMenu.items.length) {
+ panels.mainMenu.items.push({ isSeparator: true, key: `${key}separator` });
+ }
+
+ panels.mainMenu.items.push(...sortedItems);
+ });
+
  const panelList = Object.values(panels);
+
  return removePanelMetaFields(panelList);
 }

src/plugins/ui_actions/public/util/presentable.ts

@@ -94,6 +94,14 @@ export interface PresentableGroup<Context extends object = object>
  Pick<Presentable<Context>, 'getDisplayName' | 'getDisplayNameTooltip' | 'getIconType' | 'order'>
  > {
  id: string;
+ /**
+ * This allows groups to be categorized with other groups. Within a UI action
+ * context menu, this means that an item, which links to a group, will be
+ * placed in the menu adjacent to similar items that link to groups of the
+ * same category.
+ * See PanelGroupOptionsAndContextActions example to learn more.
+ */
+ category?: string;
 }
 
 export type PresentableGrouping<Context extends object = object> = Array<PresentableGroup<Context>>;