[BulkActions] Add titles to sections if provided (#11674)

### WHY are these changes introduced?

We should show the title in a section given to the ActionList within the
BulkActions if one is provided via props. This PR also updates the logic
of how we show combined flat and deep arrays of bulk actions, so that
flat arrays get sectioned together, and deep arrays are their own
section. Documentation also updated to show an example of a deep array
as a `bulkActions` prop as this was missing from storybook/doc site


### How to 🎩

🖥 [Local development
instructions](https://github.com/Shopify/polaris/blob/main/README.md#install-dependencies-and-build-workspaces)
🗒 [General tophatting
guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md)
📄 [Changelog
guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog)

Spin URL:
https://admin.web.bulk-actions-title.marc-thomas.eu.spin.dev/store/shop1/products/9

### 🎩 checklist

- [x] Tested a
[snapshot](https://github.com/Shopify/polaris/blob/main/documentation/Releasing.md#-snapshot-releases)
- [x] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [x] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [x] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [x] Updated the component's `README.md` with documentation changes
- [x] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

.changeset/forty-pigs-rule.md

@@ -0,0 +1,6 @@
+---
+'@shopify/polaris': minor
+'polaris.shopify.com': minor
+---
+
+Updated BulkActions to show titles of sections if provided

polaris-react/src/components/BulkActions/BulkActions.tsx

@@ -291,17 +291,34 @@ export const BulkActions = forwardRef(function BulkActions(
     if (!actions) {
       return [];
     }
+    let isAFlatArray = true;
     return actions
       .filter((action) => action)
-      .map(
-        (action: BulkAction | MenuGroupDescriptor | BulkActionListSection) => {
+      .reduce(
+        (
+          memo: BulkActionListSection[],
+          action: BulkAction | BulkActionListSection,
+        ): BulkActionListSection[] => {
           if (instanceOfBulkActionListSection(action)) {
-            return {items: [...action.items]};
-          } else if (instanceOfMenuGroupDescriptor(action)) {
-            return {items: [...action.actions]};
+            isAFlatArray = false;
+            return memo.concat(action);
           }
-          return {items: [action]};
+          if (isAFlatArray) {
+            if (memo.length === 0) {
+              return [{items: [action]}];
+            }
+            const lastItem = memo[memo.length - 1];
+            memo.splice(memo.length - 1, 1, {
+              items: [...lastItem.items, action],
+            });
+            return memo;
+          }
+
+          isAFlatArray = true;
+
+          return memo.concat({items: [action]});
         },
+        [],
       );
   }, [actions, actionSections]);
 

polaris-react/src/components/BulkActions/tests/BulkActions.test.tsx

@@ -158,6 +158,75 @@ describe('<BulkActions />', () => {
         ],
       });
     });
+
+    it('renders a combination of flat and deep actions in sections', () => {
+      const bulkActions = mountWithApp(
+        <BulkActions
+          {...bulkActionProps}
+          promotedActions={[]}
+          actions={[
+            {content: 'Action 1'},
+            {content: 'Action 2'},
+            {content: 'Action 3'},
+            {
+              title: 'Action group',
+              items: [
+                {content: 'Action 4'},
+                {content: 'Action 5'},
+                {content: 'Action 6'},
+              ],
+            },
+            {content: 'Action 7'},
+            {content: 'Action 8'},
+            {
+              title: 'Action group 2',
+              items: [
+                {content: 'Action 9'},
+                {content: 'Action 10'},
+                {content: 'Action 11'},
+              ],
+            },
+            {content: 'Action 12'},
+          ]}
+        />,
+      );
+
+      bulkActions.find(BulkActionButton)?.trigger('onAction');
+
+      expect(bulkActions).toContainReactComponent(ActionList, {
+        sections: [
+          {
+            items: [
+              {content: 'Action 1'},
+              {content: 'Action 2'},
+              {content: 'Action 3'},
+            ],
+          },
+          {
+            title: 'Action group',
+            items: [
+              {content: 'Action 4'},
+              {content: 'Action 5'},
+              {content: 'Action 6'},
+            ],
+          },
+          {
+            items: [{content: 'Action 7'}, {content: 'Action 8'}],
+          },
+          {
+            title: 'Action group 2',
+            items: [
+              {content: 'Action 9'},
+              {content: 'Action 10'},
+              {content: 'Action 11'},
+            ],
+          },
+          {
+            items: [{content: 'Action 12'}],
+          },
+        ],
+      });
+    });
   });
 
   describe('loading', () => {

polaris-react/src/components/IndexTable/IndexTable.stories.tsx

@@ -1182,16 +1182,34 @@ export function WithMultiplePromotedBulkActions() {
   ];
   const bulkActions = [
     {
-      content: 'Add tags',
-      onAction: () => console.log('Todo: implement bulk add tags'),
-    },
-    {
-      content: 'Remove tags',
-      onAction: () => console.log('Todo: implement bulk remove tags'),
+      title: 'Import',
+      items: [
+        {
+          content: 'Import from PDF',
+          onAction: () => console.log('Todo: implement PDF importing'),
+        },
+        {
+          content: 'Import from CSV',
+          onAction: () => console.log('Todo: implement CSV importing'),
+        },
+      ],
     },
     {
-      content: 'Delete customers',
-      onAction: () => console.log('Todo: implement bulk delete'),
+      title: 'Customers',
+      items: [
+        {
+          content: 'Add customers',
+          onAction: () => console.log('Todo: implement Adding customers'),
+        },
+        {
+          content: 'Edit customers',
+          onAction: () => console.log('Todo: implement Editing customers'),
+        },
+        {
+          content: 'Delete customers',
+          onAction: () => console.log('Todo: implement Deleting customers'),
+        },
+      ],
     },
   ];
 

polaris.shopify.com/pages/examples/index-table-with-multiple-promoted-bulk-actions.tsx

@@ -99,6 +99,19 @@ function IndexTableWithMultiplePromotedBulkActionsExample() {
       content: 'Remove tags',
       onAction: () => console.log('Todo: implement bulk remove tags'),
     },
+    {
+      title: 'Import',
+      items: [
+        {
+          content: 'Import from PDF',
+          onAction: () => console.log('Todo: implement PDF importing'),
+        },
+        {
+          content: 'Import from CSV',
+          onAction: () => console.log('Todo: implement CSV importing'),
+        },
+      ],
+    },
     {
       content: 'Delete customers',
       onAction: () => console.log('Todo: implement bulk delete'),