feat: folders (#10030)

Author: JarrodMFlesch

.vscode/launch.json

@@ -118,6 +118,13 @@
       "request": "launch",
       "type": "node-terminal"
     },
+    {
+      "command": "pnpm tsx --no-deprecation test/dev.ts folder-view",
+      "cwd": "${workspaceFolder}",
+      "name": "Run Dev Folder View",
+      "request": "launch",
+      "type": "node-terminal"
+    },
     {
       "command": "pnpm tsx --no-deprecation test/dev.ts localization",
       "cwd": "${workspaceFolder}",

docs/configuration/collections.mdx

@@ -132,6 +132,7 @@ The following options are available:
 | `hideAPIURL`                 | Hides the "API URL" meta field while editing documents within this Collection.                                                                                                                                                                          |
 | `enableRichTextLink`         | The [Rich Text](../fields/rich-text) field features a `Link` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default.                                                              |
 | `enableRichTextRelationship` | The [Rich Text](../fields/rich-text) field features a `Relationship` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default.                                                      |
+| `folders`                    | A boolean to enable folders for a given collection. Defaults to `false`. [More details](../folders/overview).                                                                                                                                           |
 | `meta`                       | Page metadata overrides to apply to this Collection within the Admin Panel. [More details](../admin/metadata).                                                                                                                                          |
 | `preview`                    | Function to generate preview URLs within the Admin Panel that can point to your app. [More details](../admin/preview).                                                                                                                                  |
 | `livePreview`                | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview).                                                                                                                           |

docs/configuration/overview.mdx

@@ -84,6 +84,7 @@ The following options are available:
 | **`csrf`**                 | A whitelist array of URLs to allow Payload to accept cookies from. [More details](../authentication/cookies#csrf-attacks).                                                                     |
 | **`defaultDepth`**         | If a user does not specify `depth` while requesting a resource, this depth will be used. [More details](../queries/depth).                                                                     |
 | **`defaultMaxTextLength`** | The maximum allowed string length to be permitted application-wide. Helps to prevent malicious public document creation.                                                                       |
+| `folders`                  | An optional object to configure global folder settings. [More details](../folders/overview).                                                                                                   |
 | `queryPresets`             | An object that to configure Collection Query Presets. [More details](../query-presets/overview).                                                                                               |
 | **`maxDepth`**             | The maximum allowed depth to be permitted application-wide. This setting helps prevent against malicious queries. Defaults to `10`. [More details](../queries/depth).                          |
 | **`indexSortableFields`**  | Automatically index all sortable top-level fields in the database to improve sort performance and add database compatibility for Azure Cosmos and similar.                                     |

docs/folders/overview.mdx

@@ -0,0 +1,100 @@
+---
+title: Folders
+label: Folders
+order: 10
+desc: Folders allow you to group documents across collections, and are a great way to organize your content.
+keywords: folders, folder, content organization
+---
+
+Folders allow you to group documents across collections, and are a great way to organize your content. Folders are built on top of relationship fields, when you enable folders on a collection, Payload adds a hidden relationship field `folders`, that relates to a folder — or no folder. Folders also have the `folder` field, allowing folders to be nested within other folders.
+
+The configuration for folders is done in two places, the collection config and the Payload config. The collection config is where you enable folders, and the Payload config is where you configure the global folder settings.
+
+## Folder Configuration
+
+On the payload config, you can configure the following settings under the `folders` property:
+
+```ts
+// Type definition
+
+type RootFoldersConfiguration = {
+  /**
+   * An array of functions to be ran when the folder collection is initialized
+   * This allows plugins to modify the collection configuration
+   */
+  collectionOverrides?: (({
+    collection,
+  }: {
+    collection: CollectionConfig
+  }) => CollectionConfig | Promise<CollectionConfig>)[]
+  /**
+   * Ability to view hidden fields and collections related to folders
+   *
+   * @default false
+   */
+  debug?: boolean
+  /**
+   * The Folder field name
+   *
+   * @default "folder"
+   */
+  fieldName?: string
+  /**
+   * Slug for the folder collection
+   *
+   * @default "payload-folders"
+   */
+  slug?: string
+}
+```
+
+```ts
+// Example usage
+
+import { buildConfig } from 'payload'
+
+const config = buildConfig({
+  // ...
+  folders: {
+    // highlight-start
+    debug: true, // optional
+    collectionOverrides: [
+      async ({ collection }) => {
+        return collection
+      },
+    ], // optional
+    fieldName: 'folder', // optional
+    slug: 'payload-folders', // optional
+    // highlight-end
+  },
+})
+```
+
+## Collection Configuration
+
+To enable folders on a collection, you need to set the `admin.folders` property to `true` on the collection config. This will add a hidden relationship field to the collection that relates to a folder — or no folder.
+
+```ts
+// Type definition
+
+type CollectionFoldersConfiguration = boolean
+```
+
+```ts
+// Example usage
+
+import { buildConfig } from 'payload'
+
+const config = buildConfig({
+  collections: [
+    {
+      slug: 'pages',
+      // highlight-start
+      admin: {
+        folders: true, // defaults to false
+      },
+      // highlight-end
+    },
+  ],
+})
+```

docs/getting-started/installation.mdx

@@ -81,7 +81,7 @@ To install a Database Adapter, you can run **one** of the following commands:
 
 #### 2. Copy Payload files into your Next.js app folder
 
-Payload installs directly in your Next.js `/app` folder, and you'll need to place some files into that folder for Payload to run. You can copy these files from the [Blank Template](https://github.com/payloadcms/payload/tree/main/templates/blank/src/app/(payload)) on GitHub. Once you have the required Payload files in place in your `/app` folder, you should have something like this:
+Payload installs directly in your Next.js `/app` folder, and you'll need to place some files into that folder for Payload to run. You can copy these files from the [Blank Template](<https://github.com/payloadcms/payload/tree/main/templates/blank/src/app/(payload)>) on GitHub. Once you have the required Payload files in place in your `/app` folder, you should have something like this:
 
 ```plaintext
 app/

packages/next/src/elements/DocumentHeader/Tabs/Tab/TabLink.tsx

@@ -1,7 +1,7 @@
 'use client'
 import type { SanitizedConfig } from 'payload'
 
-import { Link } from '@payloadcms/ui'
+import { Button } from '@payloadcms/ui'
 import { useParams, usePathname, useSearchParams } from 'next/navigation.js'
 import { formatAdminURL } from 'payload/shared'
 import React from 'react'
@@ -13,7 +13,6 @@ export const DocumentTabLink: React.FC<{
   children?: React.ReactNode
   href: string
   isActive?: boolean
-  isCollection?: boolean
   newTab?: boolean
 }> = ({
   adminRoute,
@@ -54,19 +53,17 @@ export const DocumentTabLink: React.FC<{
     isActiveFromProps
 
   return (
-    <li
+    <Button
       aria-label={ariaLabel}
+      buttonStyle="tab"
       className={[baseClass, isActive && `${baseClass}--active`].filter(Boolean).join(' ')}
+      disabled={isActive}
+      el={!isActive || href !== pathname ? 'link' : 'div'}
+      newTab={newTab}
+      size="medium"
+      to={!isActive || href !== pathname ? hrefWithLocale : undefined}
     >
-      <Link
-        className={`${baseClass}__link`}
-        href={!isActive || href !== pathname ? hrefWithLocale : ''}
-        prefetch={false}
-        {...(newTab && { rel: 'noopener noreferrer', target: '_blank' })}
-        tabIndex={isActive ? -1 : 0}
-      >
-        {children}
-      </Link>
-    </li>
+      {children}
+    </Button>
   )
 }

packages/next/src/elements/DocumentHeader/Tabs/Tab/index.scss

@@ -1,74 +1,24 @@
-@import '../../../../scss/styles.scss';
-
 @layer payload-default {
   .doc-tab {
-    @extend %h5;
-    position: relative;
-
-    &__link {
-      text-decoration: none;
-      display: flex;
-      justify-content: center;
-      align-items: center;
-      white-space: nowrap;
-
-      // Use a pseudo element for the accessability so that it doesn't take up DOM space
-      // Also because the parent element has `overflow: hidden` which would clip an outline
-      &:focus-visible::after {
-        content: '';
-        border: var(--accessibility-outline);
-        position: absolute;
-        top: 0;
-        right: 0;
-        bottom: 0;
-        left: 0;
-        pointer-events: none;
-      }
-    }
-
-    &:focus:not(:focus-visible) {
-      opacity: 1;
-    }
-
-    &::before {
-      content: '';
-      display: block;
-      position: absolute;
-      width: 100%;
-      height: 100%;
-      border-radius: var(--style-radius-s);
-      background-color: var(--theme-elevation-50);
-      opacity: 0;
-    }
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    white-space: nowrap;
 
     &:hover {
-      &::before {
-        opacity: 1;
-      }
-
-      .doc-tab__count {
+      .pill-version-count {
         background-color: var(--theme-elevation-150);
       }
     }
 
     &--active {
-      font-weight: 600;
-      &::before {
-        opacity: 1;
-        background-color: var(--theme-elevation-100);
-      }
-
-      .doc-tab {
-        &__count {
-          background-color: var(--theme-elevation-250);
-        }
+      .pill-version-count {
+        background-color: var(--theme-elevation-250);
       }
 
       &:hover {
-        .doc-tab {
-          &__count {
-            background-color: var(--theme-elevation-250);
-          }
+        .pill-version-count {
+          background-color: var(--theme-elevation-250);
         }
       }
     }
@@ -80,16 +30,7 @@
       gap: 4px;
       width: 100%;
       height: 100%;
-      line-height: base(1.2);
-      padding: base(0.2) base(0.6);
-    }
-
-    &__count {
-      line-height: base(0.8);
-      min-width: base(0.8);
-      text-align: center;
-      background-color: var(--theme-elevation-100);
-      border-radius: var(--style-radius-s);
+      line-height: calc(var(--base) * 1.2);
     }
   }
 }

packages/next/src/elements/DocumentHeader/Tabs/Tab/index.tsx

@@ -68,7 +68,6 @@ export const DocumentTab: React.FC<
         baseClass={baseClass}
         href={href}
         isActive={isActive}
-        isCollection={!!collectionConfig && !globalConfig}
         newTab={newTab}
       >
         <span className={`${baseClass}__label`}>

packages/next/src/elements/DocumentHeader/Tabs/tabs/VersionsPill/index.scss

@@ -0,0 +1,9 @@
+@layer payload-default {
+  .pill-version-count {
+    line-height: calc(var(--base) * 0.8);
+    min-width: calc(var(--base) * 0.8);
+    text-align: center;
+    background-color: var(--theme-elevation-100);
+    border-radius: var(--style-radius-s);
+  }
+}

packages/next/src/elements/DocumentHeader/Tabs/tabs/VersionsPill/index.tsx

@@ -2,7 +2,9 @@
 import { useDocumentInfo } from '@payloadcms/ui'
 import React from 'react'
 
-import { baseClass } from '../../Tab/index.js'
+import './index.scss'
+
+const baseClass = 'pill-version-count'
 
 export const VersionsPill: React.FC = () => {
   const { versionCount } = useDocumentInfo()
@@ -11,5 +13,5 @@ export const VersionsPill: React.FC = () => {
     return null
   }
 
-  return <span className={`${baseClass}__count`}>{versionCount}</span>
+  return <span className={baseClass}>{versionCount}</span>
 }