feat: adds disableGroupBy to fields admin props (#14017)

### What?

Adds a new `disableGroupBy` admin config property for fields to control
their visibility in the list view GroupBy dropdown.

### Why

Previously, the GroupByBuilder was incorrectly using `disableListFilter`
to determine which fields to show in the group-by dropdown.

### How

- Added new `disableGroupBy` property to the field admin config types.
- Updated `GroupByBuilder` to filter fields based on `disableGroupBy`
instead of `disableListFilter`

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211511898438807

docs/fields/overview.mdx

@@ -616,8 +616,9 @@ The following options are available:
 | **`readOnly`**          | Setting a field to `readOnly` has no effect on the API whatsoever but disables the admin component's editability to prevent editors from modifying the field's value.                                                            |
 | **`disabled`**          | If a field is `disabled`, it is completely omitted from the [Admin Panel](../admin/overview) entirely.                                                                                                                           |
 | **`disableBulkEdit`**   | Set `disableBulkEdit` to `true` to prevent fields from appearing in the select options when making edits for multiple documents. Defaults to `true` for UI fields.                                                               |
-| **`disableListColumn`** | Set `disableListColumn` to `true` to prevent fields from appearing in the list view column selector.                                                                                                                             |
+| **`disableGroupBy`**    | Set `disableGroupBy` to `true` to prevent fields from appearing in the list view groupBy options. Defaults to `false`.                                                                                                           |
-| **`disableListFilter`** | Set `disableListFilter` to `true` to prevent fields from appearing in the list view filter options.                                                                                                                              |
+| **`disableListColumn`** | Set `disableListColumn` to `true` to prevent fields from appearing in the list view column selector. Defaults to `false`.                                                                                                        |
+| **`disableListFilter`** | Set `disableListFilter` to `true` to prevent fields from appearing in the list view filter options. Defaults to `false`.                                                                                                         |
 | **`hidden`**            | Will transform the field into a `hidden` input type. Its value will still submit with requests in the Admin Panel, but the field itself will not be visible to editors.                                                          |
 
 ### Field Descriptions

docs/upload/overview.mdx

@@ -202,16 +202,18 @@ Each image size also supports `admin` options to control whether it appears in t
   width: 400,
   height: 300,
   admin: {
+    disableGroupBy: true, // hide from list view groupBy options
     disableListColumn: true, // hide from list view columns
     disableListFilter: true, // hide from list view filters
   },
 }
 ```
 
-| Option                  | Description                                                                                                                      |
+| Option                  | Description                                                                                                                              |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| **`disableListColumn`** | If set to `true`, this image size will not be available as a selectable column in the collection list view. Defaults to `false`. |
+| **`disableGroupBy`**    | If set to `true`, this image size will not be available as a selectable groupBy option in the collection list view. Defaults to `false`. |
-| **`disableListFilter`** | If set to `true`, this image size will not be available as a filter option in the collection list view. Defaults to `false`.     |
+| **`disableListColumn`** | If set to `true`, this image size will not be available as a selectable column in the collection list view. Defaults to `false`.         |
+| **`disableListFilter`** | If set to `true`, this image size will not be available as a filter option in the collection list view. Defaults to `false`.             |
 
 This is useful for hiding large or rarely used image sizes from the list view UI while still keeping them available in the API.
 

packages/payload/src/config/orderable/index.ts

@@ -89,6 +89,7 @@ export const addOrderableFieldsAndHook = (
       admin: {
         disableBulkEdit: true,
         disabled: true,
+        disableGroupBy: true,
         disableListColumn: true,
         disableListFilter: true,
         hidden: true,

packages/payload/src/fields/config/types.ts

@@ -366,6 +366,11 @@ type Admin = {
   description?: Description
   disableBulkEdit?: boolean
   disabled?: boolean
+  /**
+   * Shows / hides fields from appearing in the list view groupBy options.
+   * @type boolean
+   */
+  disableGroupBy?: boolean
   /**
    * Shows / hides fields from appearing in the list view column selector.
    * @type boolean
@@ -390,6 +395,11 @@ export type AdminClient = {
   description?: StaticDescription
   disableBulkEdit?: boolean
   disabled?: boolean
+  /**
+   * Shows / hides fields from appearing in the list view groupBy options.
+   * @type boolean
+   */
+  disableGroupBy?: boolean
   /**
    * Shows / hides fields from appearing in the list view column selector.
    * @type boolean

packages/payload/src/uploads/getBaseFields.ts

@@ -170,6 +170,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
           name,
           type: 'number',
           admin: {
+            disableGroupBy: true,
             disableListColumn: true,
             disableListFilter: true,
             hidden: true,
@@ -184,7 +185,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
   }
 
   // In Payload v4, image size subfields (`url`, `width`, `height`, etc.) should
-  // default to `disableListColumn: true` and `disableListFilter: true`
+  // default to `disableGroupBy: true`, `disableListColumn: true` and `disableListFilter: true`
   // to avoid cluttering the collection list view and filters by default.
   if (uploadOptions.imageSizes) {
     uploadFields = uploadFields.concat([
@@ -199,6 +200,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
           type: 'group',
           admin: {
             hidden: true,
+            ...(size.admin?.disableGroupBy && { disableGroupBy: true }),
             ...(size.admin?.disableListColumn && { disableListColumn: true }),
             ...(size.admin?.disableListFilter && { disableListFilter: true }),
           },
@@ -207,6 +209,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
               ...url,
               admin: {
                 ...url.admin,
+                ...(size.admin?.disableGroupBy && { disableGroupBy: true }),
                 ...(size.admin?.disableListColumn && { disableListColumn: true }),
                 ...(size.admin?.disableListFilter && { disableListFilter: true }),
               },
@@ -232,6 +235,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
               ...width,
               admin: {
                 ...width.admin,
+                ...(size.admin?.disableGroupBy && { disableGroupBy: true }),
                 ...(size.admin?.disableListColumn && { disableListColumn: true }),
                 ...(size.admin?.disableListFilter && { disableListFilter: true }),
               },
@@ -240,6 +244,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
               ...height,
               admin: {
                 ...height.admin,
+                ...(size.admin?.disableGroupBy && { disableGroupBy: true }),
                 ...(size.admin?.disableListColumn && { disableListColumn: true }),
                 ...(size.admin?.disableListFilter && { disableListFilter: true }),
               },
@@ -248,6 +253,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
               ...mimeType,
               admin: {
                 ...mimeType.admin,
+                ...(size.admin?.disableGroupBy && { disableGroupBy: true }),
                 ...(size.admin?.disableListColumn && { disableListColumn: true }),
                 ...(size.admin?.disableListFilter && { disableListFilter: true }),
               },
@@ -256,6 +262,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
               ...filesize,
               admin: {
                 ...filesize.admin,
+                ...(size.admin?.disableGroupBy && { disableGroupBy: true }),
                 ...(size.admin?.disableListColumn && { disableListColumn: true }),
                 ...(size.admin?.disableListFilter && { disableListFilter: true }),
               },
@@ -264,6 +271,7 @@ export const getBaseUploadFields = ({ collection, config }: Options): Field[] =>
               ...filename,
               admin: {
                 ...filename.admin,
+                ...(size.admin?.disableGroupBy && { disableGroupBy: true }),
                 ...(size.admin?.disableListColumn && { disableListColumn: true }),
                 ...(size.admin?.disableListFilter && { disableListFilter: true }),
               },

packages/payload/src/uploads/types.ts

@@ -72,11 +72,17 @@ export type ImageSize = {
   /**
    * Admin UI options that control how this image size appears in list views.
    *
-   * NOTE: In Payload v4, these options (`disableListColumn`, `disableListFilter`)
+   * NOTE: In Payload v4, these options (`disableGroupBy`, `disableListColumn` and `disableListFilter`)
    * should default to `true` so image size subfields are hidden from list columns
    * and filters by default, reducing noise in the admin UI.
    */
   admin?: {
+    /**
+     * If set to true, this image size will not be available
+     * as a selectable groupBy option in the collection list view.
+     * @default false
+     */
+    disableGroupBy?: boolean
     /**
      * If set to true, this image size will not be available
      * as a selectable column in the collection list view.

packages/plugin-multi-tenant/src/fields/tenantField/index.ts

@@ -51,6 +51,7 @@ export const tenantField = ({
     admin: {
       allowCreate: false,
       allowEdit: false,
+      disableGroupBy: true,
       disableListColumn: true,
       disableListFilter: true,
       position: 'sidebar',

packages/ui/src/elements/GroupByBuilder/index.tsx

@@ -101,7 +101,7 @@ export const GroupByBuilder: React.FC<Props> = ({ collectionSlug, fields }) => {
           }}
           options={reducedFields.filter(
             (field) =>
-              !field.field.admin.disableListFilter &&
+              !field.field.admin.disableGroupBy &&
               field.value !== 'id' &&
               supportedFieldTypes.includes(field.field.type),
           )}

test/group-by/collections/Posts/index.ts

@@ -22,6 +22,14 @@ export const PostsCollection: CollectionConfig = {
       type: 'relationship',
       relationTo: categoriesSlug,
     },
+    {
+      name: 'virtualTitleFromCategory',
+      type: 'text',
+      virtual: 'category.title',
+      admin: {
+        disableGroupBy: true,
+      },
+    },
     {
       name: 'checkbox',
       type: 'checkbox',

test/group-by/e2e.spec.ts

@@ -804,6 +804,20 @@ test.describe('Group By', () => {
     ).toBeVisible()
   })
 
+  test('should hide field from groupBy options when admin.disableGroupBy is true', async () => {
+    await page.goto(url.list)
+    const { groupByContainer } = await openGroupBy(page)
+
+    const field = groupByContainer.locator('#group-by--field-select')
+    await field.click()
+
+    await expect(
+      field.locator('.rs__option', {
+        hasText: exactText('Virtual Title From Category'),
+      }),
+    ).toBeHidden()
+  })
+
   test.describe('Trash', () => {
     test('should show trashed docs in trash view when group-by is active', async () => {
       await page.goto(url.list)

test/group-by/payload-types.ts

@@ -127,6 +127,7 @@ export interface Post {
   id: string;
   title?: string | null;
   category?: (string | null) | Category;
+  virtualTitleFromCategory?: string | null;
   checkbox?: boolean | null;
   date?: string | null;
   tab1Field?: string | null;
@@ -321,6 +322,7 @@ export interface PayloadMigration {
 export interface PostsSelect<T extends boolean = true> {
   title?: T;
   category?: T;
+  virtualTitleFromCategory?: T;
   checkbox?: T;
   date?: T;
   tab1Field?: T;