docs: document exported TypeScript type helpers for plugins (#17336)

adds a Type Helpers section to the TypeScript overview outlining the
generic helpers exported from `payload`
(`CollectionSlug`,`DataFromCollectionSlug`, `TypedUser`, etc.) and how
they resolve via `GeneratedTypes`

Author: zubricks

docs/plugins/build-your-own.mdx

@@ -273,6 +273,49 @@ export interface PluginTypes {
 
 If possible, include [JSDoc comments](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#types-1) to describe the options and their types. This allows a developer to see details about the options in their editor.
 
+### Consuming generated types
+
+A common question when building a plugin is how to reference the type of a collection that belongs to the _end user_. At authoring time you don't know which collections the user has, so it's tempting to hand-copy a subset of their interfaces — but that is fragile and quickly drifts out of sync.
+
+Instead, use Payload's generic [type helpers](../typescript/overview#type-helpers). Because a consuming project augments the `GeneratedTypes` interface when it runs `payload generate:types`, helpers like `CollectionSlug` and `DataFromCollectionSlug` resolve to the user's _actual_ collections wherever your plugin's source is type-checked in their project:
+
+```ts
+import type {
+  CollectionSlug,
+  DataFromCollectionSlug,
+  CollectionAfterChangeHook,
+} from 'payload'
+
+export interface PluginTypes {
+  /**
+   * Collections to enable this plugin for
+   */
+  collections?: CollectionSlug[]
+}
+
+// Stays generic over whichever collection slug is passed in
+const createHook = <TSlug extends CollectionSlug>(slug: TSlug) => {
+  const hook: CollectionAfterChangeHook<DataFromCollectionSlug<TSlug>> = ({
+    doc,
+  }) => {
+    // `doc` is typed to the user's collection at `slug`
+    return doc
+  }
+  return hook
+}
+```
+
+<Banner type="info">
+  Within your plugin's own repository, `GeneratedTypes` is not augmented, so
+  these helpers fall back to loose types. To develop against real types,
+  generate them inside your `dev/` project (see the `dev:generate-types` script
+  in the [plugin template](#plugin-template)) — the concrete types materialize
+  once the plugin is installed in a project that has run `payload
+  generate:types`.
+</Banner>
+
+If your plugin needs to contribute its _own_ reusable types into the user's generated file, extend the JSON schema via [`typescript.schema`](../typescript/generating-types#custom-generated-types).
+
 ## Best practices
 
 In addition to the setup covered above, here are other best practices to follow:

docs/typescript/overview.mdx

@@ -34,3 +34,59 @@ Payload exports a number of types that you may find useful while writing your ow
 - [Collection hooks](/docs/hooks/collections#typescript)
 - [Global hooks](/docs/hooks/globals#typescript)
 - [Field hooks](/docs/hooks/fields#typescript)
+
+## Type Helpers
+
+Beyond the concrete interfaces in your generated `payload-types.ts` (`Post`, `User`, etc.), Payload exports a set of **generic type helpers** from the `payload` package. Instead of referencing a single collection by name, these resolve dynamically against _all_ of your collections and globals — which makes them especially useful in [Plugins](../plugins/build-your-own#consuming-generated-types), reusable [Hooks](../hooks/overview), and [Access Control](../access-control/overview) functions, where the exact collection may not be known ahead of time.
+
+### How they resolve
+
+When you run [`payload generate:types`](./generating-types), the generated file augments a global `GeneratedTypes` interface inside the `payload` module:
+
+```ts
+// payload-types.ts (generated)
+declare module 'payload' {
+  export interface GeneratedTypes extends Config {}
+}
+```
+
+Every helper below is generic over this augmented interface. Because the augmentation lives in _your_ project, the helpers resolve to _your_ actual collections wherever your code is type-checked — including inside a third-party plugin's source once it is installed in your project. If `GeneratedTypes` has not been augmented (for example, in a plugin's own repository before it is consumed), the helpers gracefully fall back to loose types (`string`, index signatures) rather than erroring.
+
+### Available helpers
+
+| Helper                                  | Resolves to                                                                                |
+| --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `CollectionSlug`                        | A union of all your collection slugs, e.g. `'posts' \| 'users' \| 'media'`.                |
+| `DataFromCollectionSlug<TSlug>`         | The full document type for a collection (the shape returned after read).                   |
+| `RequiredDataFromCollectionSlug<TSlug>` | The data shape accepted by `create` (system fields like `id`/`createdAt` become optional). |
+| `SelectFromCollectionSlug<TSlug>`       | The `select` type for a collection.                                                        |
+| `TypedCollection`                       | A map of every collection slug to its document type.                                       |
+| `GlobalSlug`                            | A union of all your global slugs.                                                          |
+| `TypedGlobal`                           | A map of every global slug to its data type.                                               |
+| `TypedUser`                             | The user type — a union across all auth-enabled collections.                               |
+| `TypedLocale`                           | A union of your configured locale codes (or `string` if localization is disabled).         |
+| `DefaultDocumentIDType`                 | Your database's default ID type (`string` or `number`).                                    |
+
+### Example
+
+```ts
+import type {
+  CollectionSlug,
+  DataFromCollectionSlug,
+  CollectionAfterChangeHook,
+} from 'payload'
+
+// Constrain a value to any valid collection slug
+const collections: CollectionSlug[] = ['posts', 'users']
+
+// Write a hook that stays generic over whichever slug it is attached to
+function createAuditHook<TSlug extends CollectionSlug>(slug: TSlug) {
+  const hook: CollectionAfterChangeHook<DataFromCollectionSlug<TSlug>> = ({
+    doc,
+  }) => {
+    // `doc` is fully typed to the collection at `slug`
+    return doc
+  }
+  return hook
+}
+```