feat(ui): export FieldPathContext (#13806)

Fixes #12286. Supersedes
#12290.

As of
[v3.35.0](https://github.com/payloadcms/payload/releases/tag/v3.35.0),
you are no longer able to directly pass a `path` prop to a custom field
component.

For example:

```tsx
'use client'
import React from 'react'
import { TextField } from '@payloadcms/ui'
import type { TextFieldClientComponent } from 'payload'

export const MyCustomField: TextFieldClientComponent = (props) => {
  return (
    <TextField
      {...props}
      path="path.to.some.other.field" // This will not be respected, because this field's context takes precedence
    />
  )
}
```

This was introduced in #11973 where we began passing a new
`potentiallyStalePath` arg to the `useField` hook that takes the path
from context as priority. This change was necessary in order to fix
stale paths during row manipulation while the server is processing.

To ensure field components respect your custom path, you need to wrap
your components with their own `FieldPathContext`:

```tsx
'use client'
import React from 'react'
import { TextField, FieldPathContext } from '@payloadcms/ui'
import type { TextFieldClientComponent } from 'payload'

export const MyCustomField: TextFieldClientComponent = (props) => {
  return (
    <FieldPathContext path="path.to.some.other.field">
      <TextField {...props} />
    </FieldPathContext>
  )
}
```

It's possible we can remove this in the future. I explored this in
#12290, but it may require some more substantial changes in
architecture. These exports are labeled experimental to allow for any
potential changes in behavior that we may need to make in the future.

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

Author: jacobsfletch

packages/ui/src/exports/client/index.ts

@@ -19,6 +19,7 @@ export { usePayloadAPI } from '../../hooks/usePayloadAPI.js'
 export { useResize } from '../../hooks/useResize.js'
 export { useThrottledEffect } from '../../hooks/useThrottledEffect.js'
 export { useEffectEvent } from '../../hooks/useEffectEvent.js'
+export { FieldPathContext, useFieldPath } from '../../forms/RenderFields/context.js'
 
 export { useUseTitleField } from '../../hooks/useUseAsTitle.js'
 

packages/ui/src/forms/RenderFields/context.ts

@@ -1,7 +1,36 @@
 import React from 'react'
 
+/**
+ * All fields are wrapped in a `FieldPathContext` provider by default.
+ * The `useFieldPath` hook will return this value if it exists, not the path the field was explicitly given.
+ * This means if you render a field directly, you will need to wrap it with a new `FieldPathContext` provider.
+ * Otherwise, it will return the parent's path, not the path it was explicitly given.
+ * @example
+ * ```tsx
+ * 'use client'
+ * import React from 'react'
+ * import { TextField, FieldPathContext } from '@payloadcms/ui'
+ * import type { TextFieldClientComponent } from 'payload'
+ *
+ * export const MyCustomField: TextFieldClientComponent = (props) => {
+ *   return (
+ *     <FieldPathContext path="path.to.some.other.field">
+ *       <TextField {...props} />
+ *     </FieldPathContext>
+ *   )
+ * }
+ * ```
+ *
+ * @experimental This is an experimental API and may change at any time. Use at your own discretion.
+ */
 export const FieldPathContext = React.createContext<string>(undefined)
 
+/**
+ * Gets the current field path from the nearest `FieldPathContext` provider.
+ * All fields are wrapped in this context by default.
+ *
+ * @experimental This is an experimental API and may change at any time. Use at your own discretion.
+ */
 export const useFieldPath = () => {
   const context = React.useContext(FieldPathContext)