feat(ui): supports collection scoped folders

.github/workflows/main.yml

@@ -301,6 +301,7 @@ jobs:
           - fields__collections__Text
           - fields__collections__UI
           - fields__collections__Upload
+          - folders
           - hooks
           - lexical__collections__Lexical__e2e__main
           - lexical__collections__Lexical__e2e__blocks
@@ -438,6 +439,7 @@ jobs:
           - fields__collections__Text
           - fields__collections__UI
           - fields__collections__Upload
+          - folders
           - hooks
           - lexical__collections__Lexical__e2e__main
           - lexical__collections__Lexical__e2e__blocks

packages/next/src/views/BrowseByFolder/buildView.tsx

@@ -58,20 +58,45 @@ export const buildBrowseByFolderView = async (
     throw new Error('not-found')
   }
 
-  const browseByFolderSlugs = browseByFolderSlugsFromArgs.filter(
+  const foldersSlug = config.folders.slug
+
+  /**
+   * All visiible folder enabled collection slugs that the user has read permissions for.
+   */
+  const allowReadCollectionSlugs = browseByFolderSlugsFromArgs.filter(
     (collectionSlug) =>
       permissions?.collections?.[collectionSlug]?.read &&
       visibleEntities.collections.includes(collectionSlug),
   )
 
-  const query = queryFromArgs || queryFromReq
-  const activeCollectionFolderSlugs: string[] =
-    Array.isArray(query?.relationTo) && query.relationTo.length
-      ? query.relationTo.filter(
-          (slug) =>
-            browseByFolderSlugs.includes(slug) || (config.folders && slug === config.folders.slug),
-        )
-      : [...browseByFolderSlugs, config.folders.slug]
+  const query =
+    queryFromArgs ||
+    ((queryFromReq
+      ? {
+          ...queryFromReq,
+          relationTo:
+            typeof queryFromReq?.relationTo === 'string'
+              ? JSON.parse(queryFromReq.relationTo)
+              : undefined,
+        }
+      : {}) as ListQuery)
+
+  /**
+   * If a folderID is provided and the relationTo query param exists,
+   * we filter the collection slugs to only those that are allowed to be read.
+   *
+   * If no folderID is provided, only folders should be active and displayed (the root view).
+   */
+  let collectionsToDisplay: string[] = []
+  if (folderID && Array.isArray(query?.relationTo)) {
+    collectionsToDisplay = query.relationTo.filter(
+      (slug) => allowReadCollectionSlugs.includes(slug) || slug === foldersSlug,
+    )
+  } else if (folderID) {
+    collectionsToDisplay = [...allowReadCollectionSlugs, foldersSlug]
+  } else {
+    collectionsToDisplay = [foldersSlug]
+  }
 
   const {
     routes: { admin: adminRoute },
@@ -93,14 +118,15 @@ export const buildBrowseByFolderView = async (
     },
   })
 
-  const sortPreference: FolderSortKeys = browseByFolderPreferences?.sort || '_folderOrDocumentTitle'
+  const sortPreference: FolderSortKeys = browseByFolderPreferences?.sort || 'name'
   const viewPreference = browseByFolderPreferences?.viewPreference || 'grid'
 
-  const { breadcrumbs, documents, FolderResultsComponent, subfolders } =
+  const { breadcrumbs, documents, folderAssignedCollections, FolderResultsComponent, subfolders } =
     await getFolderResultsComponentAndData({
-      activeCollectionSlugs: activeCollectionFolderSlugs,
-      browseByFolder: false,
+      browseByFolder: true,
+      collectionsToDisplay,
       displayAs: viewPreference,
+      folderAssignedCollections: collectionsToDisplay.filter((slug) => slug !== foldersSlug) || [],
       folderID,
       req: initPageResult.req,
       sort: sortPreference,
@@ -142,10 +168,33 @@ export const buildBrowseByFolderView = async (
   //   serverProps,
   // })
 
-  // documents cannot be created without a parent folder in this view
-  const allowCreateCollectionSlugs = resolvedFolderID
-    ? [config.folders.slug, ...browseByFolderSlugs]
-    : [config.folders.slug]
+  // Filter down allCollectionFolderSlugs by the ones the current folder is assingned to
+  const allAvailableCollectionSlugs =
+    folderID && Array.isArray(folderAssignedCollections) && folderAssignedCollections.length
+      ? allowReadCollectionSlugs.filter((slug) => folderAssignedCollections.includes(slug))
+      : allowReadCollectionSlugs
+
+  // Filter down activeCollectionFolderSlugs by the ones the current folder is assingned to
+  const availableActiveCollectionFolderSlugs = collectionsToDisplay.filter((slug) => {
+    if (slug === foldersSlug) {
+      return permissions?.collections?.[foldersSlug]?.read
+    } else {
+      return !folderAssignedCollections || folderAssignedCollections.includes(slug)
+    }
+  })
+
+  // Documents cannot be created without a parent folder in this view
+  const allowCreateCollectionSlugs = (
+    resolvedFolderID ? [foldersSlug, ...allAvailableCollectionSlugs] : [foldersSlug]
+  ).filter((collectionSlug) => {
+    if (collectionSlug === foldersSlug) {
+      return permissions?.collections?.[foldersSlug]?.create
+    }
+    return (
+      permissions?.collections?.[collectionSlug]?.create &&
+      visibleEntities.collections.includes(collectionSlug)
+    )
+  })
 
   return {
     View: (
@@ -154,15 +203,16 @@ export const buildBrowseByFolderView = async (
         {RenderServerComponent({
           clientProps: {
             // ...folderViewSlots,
-            activeCollectionFolderSlugs,
-            allCollectionFolderSlugs: browseByFolderSlugs,
+            activeCollectionFolderSlugs: availableActiveCollectionFolderSlugs,
+            allCollectionFolderSlugs: allAvailableCollectionSlugs,
             allowCreateCollectionSlugs,
             baseFolderPath: `/browse-by-folder`,
             breadcrumbs,
             disableBulkDelete,
             disableBulkEdit,
             documents,
             enableRowSelections,
+            folderAssignedCollections,
             folderFieldName: config.folders.fieldName,
             folderID: resolvedFolderID || null,
             FolderResultsComponent,

packages/next/src/views/CollectionFolders/buildView.tsx

@@ -97,23 +97,28 @@ export const buildCollectionFolderView = async (
       },
     })
 
-    const sortPreference: FolderSortKeys =
-      collectionFolderPreferences?.sort || '_folderOrDocumentTitle'
+    const sortPreference: FolderSortKeys = collectionFolderPreferences?.sort || 'name'
     const viewPreference = collectionFolderPreferences?.viewPreference || 'grid'
 
     const {
       routes: { admin: adminRoute },
     } = config
 
-    const { breadcrumbs, documents, FolderResultsComponent, subfolders } =
-      await getFolderResultsComponentAndData({
-        activeCollectionSlugs: [config.folders.slug, collectionSlug],
-        browseByFolder: false,
-        displayAs: viewPreference,
-        folderID,
-        req: initPageResult.req,
-        sort: sortPreference,
-      })
+    const {
+      breadcrumbs,
+      documents,
+      folderAssignedCollections,
+      FolderResultsComponent,
+      subfolders,
+    } = await getFolderResultsComponentAndData({
+      browseByFolder: false,
+      collectionsToDisplay: [config.folders.slug, collectionSlug],
+      displayAs: viewPreference,
+      folderAssignedCollections: [collectionSlug],
+      folderID,
+      req: initPageResult.req,
+      sort: sortPreference,
+    })
 
     const resolvedFolderID = breadcrumbs[breadcrumbs.length - 1]?.id
 
@@ -182,6 +187,7 @@ export const buildCollectionFolderView = async (
               disableBulkEdit,
               documents,
               enableRowSelections,
+              folderAssignedCollections,
               folderFieldName: config.folders.fieldName,
               folderID: resolvedFolderID || null,
               FolderResultsComponent,

packages/payload/src/admin/functions/index.ts

@@ -1,7 +1,7 @@
 import type { ImportMap } from '../../bin/generateImportMap/index.js'
 import type { SanitizedConfig } from '../../config/types.js'
 import type { PaginatedDocs } from '../../database/types.js'
-import type { CollectionSlug, ColumnPreference } from '../../index.js'
+import type { CollectionSlug, ColumnPreference, FolderSortKeys } from '../../index.js'
 import type { PayloadRequest, Sort, Where } from '../../types/index.js'
 import type { ColumnsFromURL } from '../../utilities/transformColumnPreferences.js'
 
@@ -78,10 +78,36 @@ export type BuildCollectionFolderViewResult = {
 }
 
 export type GetFolderResultsComponentAndDataArgs = {
-  activeCollectionSlugs: CollectionSlug[]
+  /**
+   * If true and no folderID is provided, only folders will be returned.
+   * If false, the results will include documents from the active collections.
+   */
   browseByFolder: boolean
+  /**
+   * Used to filter document types to include in the results/display.
+   *
+   * i.e. ['folders', 'posts'] will only include folders and posts in the results.
+   *
+   * collectionsToQuery?
+   */
+  collectionsToDisplay: CollectionSlug[]
+  /**
+   * Used to determine how the results should be displayed.
+   */
   displayAs: 'grid' | 'list'
+  /**
+   * Used to filter folders by the collections they are assigned to.
+   *
+   * i.e. ['posts'] will only include folders that are assigned to the posts collections.
+   */
+  folderAssignedCollections: CollectionSlug[]
+  /**
+   * The ID of the folder to filter results by.
+   */
   folderID: number | string | undefined
   req: PayloadRequest
-  sort: string
+  /**
+   * The sort order for the results.
+   */
+  sort: FolderSortKeys
 }

packages/payload/src/admin/views/folderList.ts

@@ -30,6 +30,7 @@ export type FolderListViewClientProps = {
   disableBulkEdit?: boolean
   documents: FolderOrDocument[]
   enableRowSelections?: boolean
+  folderAssignedCollections?: SanitizedCollectionConfig['slug'][]
   folderFieldName: string
   folderID: null | number | string
   FolderResultsComponent: React.ReactNode

packages/payload/src/config/defaults.ts

@@ -162,14 +162,17 @@ export const addDefaultsToConfig = (config: Config): Config => {
     ...(config.auth || {}),
   }
 
-  const hasFolderCollections = config.collections.some((collection) => Boolean(collection.folders))
-  if (hasFolderCollections) {
+  if (
+    config.folders !== false &&
+    config.collections.some((collection) => Boolean(collection.folders))
+  ) {
     config.folders = {
-      slug: foldersSlug,
-      browseByFolder: true,
-      debug: false,
-      fieldName: parentFolderFieldName,
-      ...(config.folders || {}),
+      slug: config.folders?.slug ?? foldersSlug,
+      browseByFolder: config.folders?.browseByFolder ?? true,
+      collectionOverrides: config.folders?.collectionOverrides || undefined,
+      collectionSpecific: config.folders?.collectionSpecific ?? true,
+      debug: config.folders?.debug ?? false,
+      fieldName: config.folders?.fieldName ?? parentFolderFieldName,
     }
   } else {
     config.folders = false

packages/payload/src/config/sanitize.ts

@@ -3,6 +3,7 @@ import type { AcceptedLanguages } from '@payloadcms/translations'
 import { en } from '@payloadcms/translations/languages/en'
 import { deepMergeSimple } from '@payloadcms/translations/utilities'
 
+import type { CollectionSlug, GlobalSlug, SanitizedCollectionConfig } from '../index.js'
 import type { SanitizedJobsConfig } from '../queues/config/types/index.js'
 import type {
   Config,
@@ -18,15 +19,10 @@ import { sanitizeCollection } from '../collections/config/sanitize.js'
 import { migrationsCollection } from '../database/migrations/migrationsCollection.js'
 import { DuplicateCollection, InvalidConfiguration } from '../errors/index.js'
 import { defaultTimezones } from '../fields/baseFields/timezone/defaultTimezones.js'
-import { addFolderCollections } from '../folders/addFolderCollections.js'
+import { addFolderCollection } from '../folders/addFolderCollection.js'
+import { addFolderFieldToCollection } from '../folders/addFolderFieldToCollection.js'
 import { sanitizeGlobal } from '../globals/config/sanitize.js'
-import {
-  baseBlockFields,
-  type CollectionSlug,
-  formatLabels,
-  type GlobalSlug,
-  sanitizeFields,
-} from '../index.js'
+import { baseBlockFields, formatLabels, sanitizeFields } from '../index.js'
 import {
   getLockedDocumentsCollection,
   lockedDocumentsCollectionSlug,
@@ -191,15 +187,17 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
 
   const collectionSlugs = new Set<CollectionSlug>()
 
-  await addFolderCollections(config as unknown as Config)
-
   const validRelationships = [
     ...(config.collections?.map((c) => c.slug) ?? []),
     jobsCollectionSlug,
     lockedDocumentsCollectionSlug,
     preferencesCollectionSlug,
   ]
 
+  if (config.folders !== false) {
+    validRelationships.push(config.folders!.slug)
+  }
+
   /**
    * Blocks sanitization needs to happen before collections, as collection/global join field sanitization needs config.blocks
    * to be populated with the sanitized blocks
@@ -236,6 +234,8 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
     }
   }
 
+  const folderEnabledCollections: SanitizedCollectionConfig[] = []
+
   for (let i = 0; i < config.collections!.length; i++) {
     if (collectionSlugs.has(config.collections![i]!.slug)) {
       throw new DuplicateCollection('slug', config.collections![i]!.slug)
@@ -257,12 +257,25 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
       }
     }
 
+    if (config.folders !== false && config.collections![i]!.folders) {
+      addFolderFieldToCollection({
+        collection: config.collections![i]!,
+        collectionSpecific: config.folders!.collectionSpecific,
+        folderFieldName: config.folders!.fieldName,
+        folderSlug: config.folders!.slug,
+      })
+    }
+
     config.collections![i] = await sanitizeCollection(
       config as unknown as Config,
       config.collections![i]!,
       richTextSanitizationPromises,
       validRelationships,
     )
+
+    if (config.folders !== false && config.collections![i]!.folders) {
+      folderEnabledCollections.push(config.collections![i]!)
+    }
   }
 
   if (config.globals!.length > 0) {
@@ -332,6 +345,16 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
     configWithDefaults.collections!.push(sanitizedJobsCollection)
   }
 
+  if (config.folders !== false && folderEnabledCollections.length) {
+    await addFolderCollection({
+      collectionSpecific: config.folders!.collectionSpecific,
+      config: config as unknown as Config,
+      folderEnabledCollections,
+      richTextSanitizationPromises,
+      validRelationships,
+    })
+  }
+
   configWithDefaults.collections!.push(
     await sanitizeCollection(
       config as unknown as Config,