documentation, shorter copyrighty, minor cleanup

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

examples/ui_actions_explorer/public/context_menu_examples/panel_group_options_and_context_actions.tsx

@@ -1,31 +1,6 @@
 /*
+ * Copyright OpenSearch Contributors
  * SPDX-License-Identifier: Apache-2.0
- *
- * The OpenSearch Contributors require contributions made to
- * this file be licensed under the Apache-2.0 license or a
- * compatible open source license.
- *
- * Any modifications Copyright OpenSearch Contributors. See
- * GitHub history for details.
- */
-
-/*
- * Licensed to Elasticsearch B.V. under one or more contributor
- * license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright
- * ownership. Elasticsearch B.V. licenses this file to you under
- * the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
  */
 
 import * as React from 'react';

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

@@ -501,6 +501,10 @@ test('groups with categories and order', async () => {
       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,

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

@@ -241,54 +241,60 @@ export async function buildContextMenuForActions({
   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) {
-      // If a category is specified, store either a link to the panel or the
-      // item within. We will deal with it after looping through all panels.
-      if (panel._category) {
-        // Create array to store category items
-        if (!categories[panel._category]) {
-          categories[panel._category] = [];
-        }
+    // Do nothing if not root-level panel, such as the parent of a group
+    if (panel._level !== 0) {
+      continue;
+    }
 
-        // 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,
-          });
-        }
+    // 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 {
-        // Add separator with unique key if needed
-        if (panels.mainMenu.items.length) {
-          panels.mainMenu.items.push({ isSeparator: true, key: `${panel.id}separator` });
-        }
+        categories[panel._category].push({
+          order: panel._order || 0,
+          items: panel.items,
+        });
+      }
+    } else {
+      // If no category, continue with adding items to the mainMenu
 
-        // 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.
-        // Note: this only happens on the root level panels, not for inner groups.
-        if (panel.items.length > 1) {
-          panels.mainMenu.items.push({
-            name: panel.title || panel.id,
-            icon: panel._icon || 'empty',
-            panel: panel.id,
-          });
-        } else {
-          panels.mainMenu.items.push(...panel.items);
-        }
+      // 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, 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({
+          name: panel.title || panel.id,
+          icon: panel._icon || 'empty',
+          panel: panel.id,
+        });
+      } else {
+        panels.mainMenu.items.push(...panel.items);
       }
     }
   }