Roadmap/#1379 admin ui doc level access (#1624)

* feat: adds document level access endpoints so admin ui can now accurately reflect document level access control
* chore(docs): new doc access callout, updates useDocumentInfo props from change

Author: JarrodMFlesch

docs/admin/hooks.mdx

@@ -54,10 +54,10 @@ const {
 
 ### useFormFields
 
-There are times when a custom field component needs to have access to data from other fields, and you have a few options to do so. The `useFormFields` hook is a powerful and highly performant way to retrieve a form's field state, as well as to retrieve the `dispatchFields` method, which can be helpful for setting other fields' form states from anywhere within a form.  
+There are times when a custom field component needs to have access to data from other fields, and you have a few options to do so. The `useFormFields` hook is a powerful and highly performant way to retrieve a form's field state, as well as to retrieve the `dispatchFields` method, which can be helpful for setting other fields' form states from anywhere within a form.
 
 <Banner type="success">
-  <strong>This hook is great for retrieving only certain fields from form state</strong> because it ensures that it will only cause a rerender when the items that you ask for change. 
+  <strong>This hook is great for retrieving only certain fields from form state</strong> because it ensures that it will only cause a rerender when the items that you ask for change.
 </Banner>
 
 Thanks to the awesome package [`use-context-selector`](https://github.com/dai-shi/use-context-selector), you can retrieve a specific field's state easily. This is ideal because you can ensure you have an up-to-date field state, and your component will only re-render when _that field's state_ changes.
@@ -84,7 +84,7 @@ const MyComponent: React.FC = () => {
 
 ### useAllFormFields
 
-**To retrieve more than one field**, you can use the `useAllFormFields` hook. Your component will re-render when _any_ field changes, so use this hook only if you absolutely need to. Unlike the `useFormFields` hook, this hook does not accept a "selector", and it always returns an array with type of `[fields: Fields, dispatch: React.Dispatch<Action>]]`. 
+**To retrieve more than one field**, you can use the `useAllFormFields` hook. Your component will re-render when _any_ field changes, so use this hook only if you absolutely need to. Unlike the `useFormFields` hook, this hook does not accept a "selector", and it always returns an array with type of `[fields: Fields, dispatch: React.Dispatch<Action>]]`.
 
 You can do lots of powerful stuff by retrieving the full form state, like using built-in helper functions to reduce field state to values only, or to retrieve sibling data by path.
 
@@ -100,7 +100,7 @@ const ExampleComponent: React.FC = () => {
   // The result below will reflect the data stored in the form at the given time
   const formData = reduceFieldsToValues(fields, true);
 
-  // Pass in field state and a path, 
+  // Pass in field state and a path,
   // and you will be sent all sibling data of the path that you've specified
   const siblingData = getSiblingData(fields, 'someFieldName');
 
@@ -135,7 +135,7 @@ The `useForm` hook can be used to interact with the form itself, and sends back
 
 <Banner type="warning">
   <strong>Warning:</strong><br/>
-  This hook is optimized to avoid causing rerenders when fields change, and as such, its `fields` property will be out of date. You should only leverage this hook if you need to perform actions against the form in response to your users' actions. Do not rely on its returned "fields" as being up-to-date. They will be removed from this hook's response in an upcoming version. 
+  This hook is optimized to avoid causing rerenders when fields change, and as such, its `fields` property will be out of date. You should only leverage this hook if you need to perform actions against the form in response to your users' actions. Do not rely on its returned "fields" as being up-to-date. They will be removed from this hook's response in an upcoming version.
 </Banner>
 
 The `useForm` hook returns an object with the following properties:
@@ -162,17 +162,19 @@ The `useForm` hook returns an object with the following properties:
 
 The `useDocumentInfo` hook provides lots of information about the document currently being edited, including the following:
 
-| Property                  | Description                                                                        |
-|---------------------------|------------------------------------------------------------------------------------|
-| **`collection`**          | If the doc is a collection, its collection config will be returned                 |
-| **`global`**              | If the doc is a global, its global config will be returned                         |
-| **`type`**                | The type of document being edited (collection or global)                           |
-| **`id`**                  | If the doc is a collection, its ID will be returned                                |
-| **`preferencesKey`**      | The `preferences` key to use when interacting with document-level user preferences |
-| **`versions`**            | Versions of the current doc                                                        |
-| **`unpublishedVersions`** | Unpublished versions of the current doc                                            |
-| **`publishedDoc`**        | The currently published version of the doc being edited                            |
-| **`getVersions`**         | Method to trigger the retrieval of document versions                               |
+| Property                  | Description                                                                                                        |
+|---------------------------|--------------------------------------------------------------------------------------------------------------------|                                |
+| **`collection`**          | If the doc is a collection, its collection config will be returned                                                 |
+| **`global`**              | If the doc is a global, its global config will be returned                                                         |
+| **`type`**                | The type of document being edited (collection or global)                                                           |
+| **`id`**                  | If the doc is a collection, its ID will be returned                                                                |
+| **`preferencesKey`**      | The `preferences` key to use when interacting with document-level user preferences                                 |
+| **`versions`**            | Versions of the current doc                                                                                        |
+| **`unpublishedVersions`** | Unpublished versions of the current doc                                                                            |
+| **`publishedDoc`**        | The currently published version of the doc being edited                                                            |
+| **`getVersions`**         | Method to trigger the retrieval of document versions                                                               |
+| **`docPermissions`**      | The current documents permissions. Collection document permissions fallback when no id is present (i.e. on create) |
+| **`getDocPermissions`**   | Method to trigger the retrieval of document level permissions                                                      |
 
 **Example:**
 
@@ -250,7 +252,7 @@ const Greeting: React.FC = () => {
 
 ### useConfig
 
-Used to easily fetch the full Payload config. 
+Used to easily fetch the full Payload config.
 
 ```tsx
 import { useConfig } from 'payload/components/utilities';

docs/authentication/operations.mdx

@@ -66,6 +66,8 @@ query {
 }
 ```
 
+Document access can also be queried on a collection/global basis. Access on a global can queried like `http://localhost:3000/api/global-slug/access`, Collection document access can be queried like `http://localhost:3000/api/collection-slug/access/:id`.
+
 ### Me
 
 Returns either a logged in user with token or null when there is no logged in user.

src/admin/components/utilities/DocumentInfo/index.tsx

@@ -5,12 +5,13 @@ import qs from 'qs';
 import { useTranslation } from 'react-i18next';
 import { useConfig } from '../Config';
 import { PaginatedDocs } from '../../../../mongoose/types';
-import { ContextType, Props, Version } from './types';
+import { ContextType, DocumentPermissions, EntityType, Props, Version } from './types';
 import { TypeWithID } from '../../../../globals/config/types';
 import { TypeWithTimestamps } from '../../../../collections/config/types';
 import { Where } from '../../../../types';
 import { DocumentPreferences } from '../../../../preferences/types';
 import { usePreferences } from '../Preferences';
+import { useAuth } from '../Auth';
 
 const Context = createContext({} as ContextType);
 
@@ -23,24 +24,29 @@ export const DocumentInfoProvider: React.FC<Props> = ({
   const { serverURL, routes: { api } } = useConfig();
   const { getPreference } = usePreferences();
   const { i18n } = useTranslation();
+  const { permissions } = useAuth();
   const [publishedDoc, setPublishedDoc] = useState<TypeWithID & TypeWithTimestamps>(null);
   const [versions, setVersions] = useState<PaginatedDocs<Version>>(null);
   const [unpublishedVersions, setUnpublishedVersions] = useState<PaginatedDocs<Version>>(null);
+  const [docPermissions, setDocPermissions] = useState<DocumentPermissions>(null);
 
   const baseURL = `${serverURL}${api}`;
-  let slug;
-  let type;
-  let preferencesKey;
+  let slug: string;
+  let type: EntityType;
+  let pluralType: 'globals' | 'collections';
+  let preferencesKey: string;
 
   if (global) {
     slug = global.slug;
     type = 'global';
+    pluralType = 'globals';
     preferencesKey = `global-${slug}`;
   }
 
   if (collection) {
     slug = collection.slug;
     type = 'collection';
+    pluralType = 'collections';
 
     if (id) {
       preferencesKey = `collection-${slug}-${id}`;
@@ -169,6 +175,25 @@ export const DocumentInfoProvider: React.FC<Props> = ({
     }
   }, [i18n, global, collection, id, baseURL]);
 
+  const getDocPermissions = React.useCallback(async () => {
+    let docAccessURL: string;
+    if (pluralType === 'globals') {
+      docAccessURL = `/globals/${slug}/access`;
+    } else if (pluralType === 'collections' && id) {
+      docAccessURL = `/${slug}/access/${id}`;
+    }
+
+    if (docAccessURL) {
+      const res = await fetch(`${serverURL}${api}${docAccessURL}`);
+      const json = await res.json();
+      setDocPermissions(json);
+    } else {
+      // fallback to permissions from the collection
+      // (i.e. create has no id)
+      setDocPermissions(permissions[pluralType][slug]);
+    }
+  }, [serverURL, api, pluralType, slug, id, permissions]);
+
   useEffect(() => {
     getVersions();
   }, [getVersions]);
@@ -181,6 +206,10 @@ export const DocumentInfoProvider: React.FC<Props> = ({
     getDocPreferences();
   }, [getPreference, preferencesKey]);
 
+  useEffect(() => {
+    getDocPermissions();
+  }, [getDocPermissions]);
+
   const value = {
     slug,
     type,
@@ -192,6 +221,8 @@ export const DocumentInfoProvider: React.FC<Props> = ({
     getVersions,
     publishedDoc,
     id,
+    getDocPermissions,
+    docPermissions,
   };
 
   return (
@@ -202,5 +233,3 @@ export const DocumentInfoProvider: React.FC<Props> = ({
 };
 
 export const useDocumentInfo = (): ContextType => useContext(Context);
-
-export default Context;

src/admin/components/utilities/DocumentInfo/types.ts

@@ -1,15 +1,20 @@
 import React from 'react';
+import { CollectionPermission, GlobalPermission } from '../../../../auth';
 import { SanitizedCollectionConfig, TypeWithID, TypeWithTimestamps } from '../../../../collections/config/types';
 import { SanitizedGlobalConfig } from '../../../../globals/config/types';
 import { PaginatedDocs } from '../../../../mongoose/types';
 import { TypeWithVersion } from '../../../../versions/types';
 
 export type Version = TypeWithVersion<any>
 
+export type DocumentPermissions = null | GlobalPermission | CollectionPermission
+
+export type EntityType = 'global' | 'collection'
+
 export type ContextType = {
   collection?: SanitizedCollectionConfig
   global?: SanitizedGlobalConfig
-  type: 'global' | 'collection'
+  type: EntityType
   /** Slug of the collection or global */
   slug?: string
   id?: string | number
@@ -18,6 +23,8 @@ export type ContextType = {
   unpublishedVersions?: PaginatedDocs<Version>
   publishedDoc?: TypeWithID & TypeWithTimestamps & { _status?: string }
   getVersions: () => Promise<void>
+  docPermissions: DocumentPermissions
+  getDocPermissions: () => Promise<void>
 }
 
 export type Props = {

src/admin/components/views/Global/index.tsx

@@ -20,9 +20,9 @@ const GlobalView: React.FC<IndexProps> = (props) => {
   const { state: locationState } = useLocation<{data?: Record<string, unknown>}>();
   const locale = useLocale();
   const { setStepNav } = useStepNav();
-  const { permissions, user } = useAuth();
+  const { user } = useAuth();
   const [initialState, setInitialState] = useState<Fields>();
-  const { getVersions, preferencesKey } = useDocumentInfo();
+  const { getVersions, preferencesKey, docPermissions, getDocPermissions } = useDocumentInfo();
   const { getPreference } = usePreferences();
   const { t } = useTranslation();
 
@@ -50,9 +50,10 @@ const GlobalView: React.FC<IndexProps> = (props) => {
 
   const onSave = useCallback(async (json) => {
     getVersions();
+    getDocPermissions();
     const state = await buildStateFromSchema({ fieldSchema: fields, data: json.result, operation: 'update', user, locale, t });
     setInitialState(state);
-  }, [getVersions, fields, user, locale, t]);
+  }, [getVersions, fields, user, locale, t, getDocPermissions]);
 
   const [{ data }] = usePayloadAPI(
     `${serverURL}${api}/globals/${slug}`,
@@ -79,16 +80,14 @@ const GlobalView: React.FC<IndexProps> = (props) => {
     awaitInitialState();
   }, [dataToRender, fields, user, locale, getPreference, preferencesKey, t]);
 
-  const globalPermissions = permissions?.globals?.[slug];
-
   return (
     <RenderCustomComponent
       DefaultComponent={DefaultGlobal}
       CustomComponent={CustomEdit}
       componentProps={{
-        isLoading: !initialState,
+        isLoading: !initialState || !docPermissions,
         data: dataToRender,
-        permissions: globalPermissions,
+        permissions: docPermissions,
         initialState,
         global,
         onSave,

src/admin/components/views/collections/Edit/index.tsx

@@ -15,6 +15,7 @@ import { useDocumentInfo } from '../../../utilities/DocumentInfo';
 import { Fields } from '../../../forms/Form/types';
 import { usePreferences } from '../../../utilities/Preferences';
 import { EditDepthContext } from '../../../utilities/EditDepth';
+import { CollectionPermission } from '../../../../../auth';
 
 const EditView: React.FC<IndexProps> = (props) => {
   const { collection: incomingCollection, isEditing } = props;
@@ -40,20 +41,21 @@ const EditView: React.FC<IndexProps> = (props) => {
   const { state: locationState } = useLocation();
   const history = useHistory();
   const [initialState, setInitialState] = useState<Fields>();
-  const { permissions, user } = useAuth();
-  const { getVersions, preferencesKey } = useDocumentInfo();
+  const { user } = useAuth();
+  const { getVersions, preferencesKey, getDocPermissions, docPermissions } = useDocumentInfo();
   const { getPreference } = usePreferences();
   const { t } = useTranslation('general');
 
   const onSave = useCallback(async (json: any) => {
     getVersions();
+    getDocPermissions();
     if (!isEditing) {
       setRedirect(`${admin}/collections/${collection.slug}/${json?.doc?.id}`);
     } else {
       const state = await buildStateFromSchema({ fieldSchema: collection.fields, data: json.doc, user, id, operation: 'update', locale, t });
       setInitialState(state);
     }
-  }, [admin, collection, isEditing, getVersions, user, id, t, locale]);
+  }, [admin, collection, isEditing, getVersions, user, id, t, locale, getDocPermissions]);
 
   const [{ data, isLoading: isLoadingDocument, isError }] = usePayloadAPI(
     (isEditing ? `${serverURL}${api}/${slug}/${id}` : null),
@@ -87,10 +89,9 @@ const EditView: React.FC<IndexProps> = (props) => {
     );
   }
 
-  const collectionPermissions = permissions?.collections?.[slug];
   const apiURL = `${serverURL}${api}/${slug}/${id}${collection.versions.drafts ? '?draft=true' : ''}`;
   const action = `${serverURL}${api}/${slug}${isEditing ? `/${id}` : ''}?locale=${locale}&depth=0&fallback-locale=null`;
-  const hasSavePermission = (isEditing && collectionPermissions?.update?.permission) || (!isEditing && collectionPermissions?.create?.permission);
+  const hasSavePermission = (isEditing && docPermissions?.update?.permission) || (!isEditing && (docPermissions as CollectionPermission)?.create?.permission);
 
   return (
     <EditDepthContext.Provider value={1}>
@@ -99,10 +100,10 @@ const EditView: React.FC<IndexProps> = (props) => {
         CustomComponent={CustomEdit}
         componentProps={{
           id,
-          isLoading: !initialState,
+          isLoading: !initialState || !docPermissions,
           data: dataToRender,
           collection,
-          permissions: collectionPermissions,
+          permissions: docPermissions,
           isEditing,
           onSave,
           initialState,