@payloadcms/codemod 4.0.0-canary.38 → 4.0.0-canary.39

package/README.md

@@ -87,10 +87,12 @@ The tool loads your project via [ts-morph](https://ts-morph.com/), using your `t
 - `globals-components-edit`: Globals: rename `admin.components.elements` to `admin.components.edit` and hoist `Description` to top-level `admin.components.Description` to match Collection conventions.
 - `migrate-force-select`: migrates `forceSelect: { ... }` on Collection/Global configs to a `select` function that augments the caller's `select` when present and returns `undefined` (preserving full-document reads) when not. Shallow values become a spread (`{ ...select, ... }`); nested values use `deepMergeSimple` from `payload/shared` (auto-imported) to preserve the previous deep-merge semantics. Non-literal values, sibling `select` already present, and unsupported member kinds are surfaced as notes for manual review.
 - `migrate-field-component-types`: replaces field component aliases—including concrete fields, canonical generics, labels, descriptions, errors, diffs, and block row labels—with the corresponding props types wrapped in `React.FC`. Generic arguments are preserved. Explicit class components, re-exports, namespace references, and inline imports are left unchanged with notes for manual migration.
+- `rename-diff-value-props`: renames the `comparisonValue` and `versionValue` props read by custom Diff components to `valueFrom` and `valueTo`. Detects components whose props are typed with a Diff type imported from `payload`, in either the v3 component form (`TextFieldDiffClientComponent`) or the props form (`TextFieldDiffClientProps`), including same-file type aliases and interfaces built from one. Renames destructured props (along with the local variables they declare, unless the new name is already taken), `props.comparisonValue` and `props['comparisonValue']` reads, and `TextFieldDiffClientProps['comparisonValue']` indexed access types. Untyped components are not detected; remaining old prop names in property positions (e.g. JSX attributes passed to other components) are surfaced as notes in files that import a Diff type.
 - `migrate-block-references-to-blocks`: renames blocks field `blockReferences` configs to `blocks`, and removes a sibling `blocks: []` placeholder when present. If a non-empty `blocks` sibling already exists, the transform leaves the field untouched and surfaces a note for manual review.
 - `migrate-hide-api-url`: migrates `admin.hideAPIURL: true` to `admin.components.views.edit.api.tab.condition: () => false` on collection and global configs.
 - `migrate-aliased-exports`: rewrites imports of types and utilities that used to be re-exported from `@payloadcms/ui` and `@payloadcms/next/utilities` to their canonical sources in `payload` / `payload/shared`.
 - `migrate-payload-request-creation`: renames named request-helper and admin-context imports from `payload` and `payload/internal`. Calls migrate only with a plain identifier payload and either `{}` or an initialized local `const` options identifier whose type exposes all seven old option properties (or is `any`). The generated argument captures payload first and forwards only `context`, `depth`, `fallbackLocale`, `locale`, `req`, `urlSuffix`, and `user` through getters, preserving inherited getters, read order, and async rejection behavior. Existing `CreateLocalReqOptions` named imports from `payload` become options-only usages of `Omit<CreatePayloadRequestArgs, 'payload'>`; relative/private imports of that internal type require manual migration. Unsupported shapes, type usages, and collisions leave the affected binding unchanged with notes.
+- `migrate-admin-context-properties`: rewrites reads of `headers` and `languageCode`, removed from `AdminContext` in v4, to `req.headers` and `req.i18n.language` (`i18n.language` on `PartialAdminContext`). Covers `initAdminContext()` results (property access, destructures, and `const` bindings), parameters and variables typed as `AdminContext`, and `Pick<AdminContext, ...>` and `AdminContext['...']` types. Drops both arguments from `getRootLayoutData()` calls, then drops destructured bindings that are no longer read. Element access such as `context['headers']` and `Pick` types that only pick removed properties are left unchanged with notes. Run after `migrate-payload-request-creation`; the default run order handles this.
 - `migrate-document-title-context`: migrates `title` and `setDocumentTitle` destructured from `useDocumentInfo()` to `useDocumentTitle()`. They were removed from `DocumentInfoContext` in v4 and now live on `DocumentTitleContext`.
 - `migrate-sharp-to-transformer`: moves a top-level `sharp` dependency and per-collection Sharp-specific `upload` options (`resizeOptions`, `imageSizes`, `formatOptions`, `trimOptions`, `constructorOptions`, `withMetadata`, `crop`, `focalPoint`) into `sharpTransformer({ collections })`, registered under `upload.transformers`. Appends to an existing `transformers` array instead of overwriting it, and no-ops if a `sharpTransformer` call is already present. **Limitations:** only inline `buildConfig({...})` object literals and inline collection/`upload` object literals are migrated; a dynamic `collections` array, an externally-defined collection, or a non-inline `upload` object are left untouched with a note for manual review. A collection's `upload` object built from a spread (e.g. `upload: { ...sharedUploadConfig }`) is noted for manual review, since Sharp-specific fields hidden inside the spread aren't visible to the transform and are left un-migrated. Surfaces a note reminding you to install `@payloadcms/transformer-sharp` (`pnpm add @payloadcms/transformer-sharp`). The transform preserves AST structure but does not re-format output. Run `prettier --write` (or your project's formatter) after applying.
 - `migrate-storage-adapters-to-config`: moves storage adapter factory calls (`s3Storage`, `gcsStorage`, `azureStorage`, `r2Storage`, `vercelBlobStorage`) from `plugins` to the new top-level `storage` array. Removes `plugins` if it becomes empty after the move. **Limitations:** aliased imports (e.g. `import { s3Storage as myS3 }`) are not detected; rename any aliases to the canonical factory name before running, or migrate those calls manually. The transform preserves AST structure but does not re-format output. Run `prettier --write` (or your project's formatter) after applying.

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAoC3C,eAAO,MAAM,UAAU,EAAE,SAAS,EAkCjC,CAAA"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAsC3C,eAAO,MAAM,UAAU,EAAE,SAAS,EAoCjC,CAAA"}

package/dist/registry.js

@@ -1,6 +1,7 @@
 import { addOverrideAccessTrue } from './transforms/add-override-access-true/index.js';
 import { exampleNoop } from './transforms/example-noop/index.js';
 import { globalsComponentsEdit } from './transforms/globals-components-edit/index.js';
+import { migrateAdminContextProperties } from './transforms/migrate-admin-context-properties/index.js';
 import { migrateAfterOperationRead } from './transforms/migrate-after-operation-read/index.js';
 import { migrateAliasedExports } from './transforms/migrate-aliased-exports/index.js';
 import { migrateAuthorshipDefault } from './transforms/migrate-authorship-default/index.js';
@@ -28,6 +29,7 @@ import { removeLocalizeStatusConfig } from './transforms/remove-localize-status-
 import { removePublishSpecificLocale } from './transforms/remove-publish-specific-locale/index.js';
 import { removeStorageAlwaysInsertFields } from './transforms/remove-storage-always-insert-fields/index.js';
 import { removeVersionsTrue } from './transforms/remove-versions-true/index.js';
+import { renameDiffValueProps } from './transforms/rename-diff-value-props/index.js';
 import { renameExperimentalTableFeature } from './transforms/rename-experimental-table-feature/index.js';
 import { renameStorageAdaptersToStorage } from './transforms/rename-storage-adapters-to-storage/index.js';
 import { renameTypescriptSchemaToJsonSchema } from './transforms/rename-typescript-schema-to-json-schema/index.js';
@@ -41,8 +43,10 @@ export const transforms = [
     migrateDisabledFields,
     migrateForceSelect,
     migrateFieldComponentTypes,
+    renameDiffValueProps,
     migrateAliasedExports,
     migratePayloadRequestCreation,
+    migrateAdminContextProperties,
     migrateBlockReferencesToBlocks,
     migrateBuildScript,
     migrateDocumentTitleContext,

package/dist/registry.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/registry.ts"],"sourcesContent":["import type { Transform } from './types.js'\n\nimport { addOverrideAccessTrue } from './transforms/add-override-access-true/index.js'\nimport { exampleNoop } from './transforms/example-noop/index.js'\nimport { globalsComponentsEdit } from './transforms/globals-components-edit/index.js'\nimport { migrateAfterOperationRead } from './transforms/migrate-after-operation-read/index.js'\nimport { migrateAliasedExports } from './transforms/migrate-aliased-exports/index.js'\nimport { migrateAuthorshipDefault } from './transforms/migrate-authorship-default/index.js'\nimport { migrateAzureChunkLargeFiles } from './transforms/migrate-azure-chunk-large-files/index.js'\nimport { migrateBlockReferencesToBlocks } from './transforms/migrate-block-references-to-blocks/index.js'\nimport { migrateBuildScript } from './transforms/migrate-build-script/index.js'\nimport { migrateDbTypesSubpath } from './transforms/migrate-db-types-subpath/index.js'\nimport { migrateDisabledFields } from './transforms/migrate-disabled-fields/index.js'\nimport { migrateDocumentTitleContext } from './transforms/migrate-document-title-context/index.js'\nimport { migrateFieldComponentTypes } from './transforms/migrate-field-component-types/index.js'\nimport { migrateForceSelect } from './transforms/migrate-force-select/index.js'\nimport { migrateHideAPIURL } from './transforms/migrate-hide-api-url/index.js'\nimport { migrateImportExportHooks } from './transforms/migrate-import-export-hooks/index.js'\nimport { migrateListViewSelectAPI } from './transforms/migrate-list-view-select-api/index.js'\nimport { migrateNextGenerateViewportExport } from './transforms/migrate-next-generate-viewport-export/index.js'\nimport { migrateNextSubpathExports } from './transforms/migrate-next-subpath-exports/index.js'\nimport { migratePayloadRequestCreation } from './transforms/migrate-payload-request-creation/index.js'\nimport { migrateSharpToTransformer } from './transforms/migrate-sharp-to-transformer/index.js'\nimport { migrateSlugField } from './transforms/migrate-slug-field/index.js'\nimport { migrateStorageAdaptersToConfig } from './transforms/migrate-storage-adapters-to-config/index.js'\nimport { migrateVersionsDefault } from './transforms/migrate-versions-default/index.js'\nimport { removeDefaultLocalePublishOption } from './transforms/remove-default-locale-publish-option/index.js'\nimport { removeGroupByTrue } from './transforms/remove-group-by-true/index.js'\nimport { removeLocalizeStatusConfig } from './transforms/remove-localize-status-config/index.js'\nimport { removePublishSpecificLocale } from './transforms/remove-publish-specific-locale/index.js'\nimport { removeStorageAlwaysInsertFields } from './transforms/remove-storage-always-insert-fields/index.js'\nimport { removeVersionsTrue } from './transforms/remove-versions-true/index.js'\nimport { renameExperimentalTableFeature } from './transforms/rename-experimental-table-feature/index.js'\nimport { renameStorageAdaptersToStorage } from './transforms/rename-storage-adapters-to-storage/index.js'\nimport { renameTypescriptSchemaToJsonSchema } from './transforms/rename-typescript-schema-to-json-schema/index.js'\n\nexport const transforms: Transform[] = [\n  exampleNoop,\n  addOverrideAccessTrue,\n  migrateAfterOperationRead,\n  migrateHideAPIURL,\n  globalsComponentsEdit,\n  migrateListViewSelectAPI,\n  migrateDisabledFields,\n  migrateForceSelect,\n  migrateFieldComponentTypes,\n  migrateAliasedExports,\n  migratePayloadRequestCreation,\n  migrateBlockReferencesToBlocks,\n  migrateBuildScript,\n  migrateDocumentTitleContext,\n  migrateSharpToTransformer,\n  migrateStorageAdaptersToConfig,\n  migrateAzureChunkLargeFiles,\n  renameStorageAdaptersToStorage,\n  migrateImportExportHooks,\n  migrateDbTypesSubpath,\n  migrateNextGenerateViewportExport,\n  migrateNextSubpathExports,\n  migrateSlugField,\n  migrateVersionsDefault,\n  migrateAuthorshipDefault,\n  removeDefaultLocalePublishOption,\n  removeGroupByTrue,\n  removeLocalizeStatusConfig,\n  removeVersionsTrue,\n  removePublishSpecificLocale,\n  removeStorageAlwaysInsertFields,\n  renameTypescriptSchemaToJsonSchema,\n  renameExperimentalTableFeature,\n]\n"],"names":["addOverrideAccessTrue","exampleNoop","globalsComponentsEdit","migrateAfterOperationRead","migrateAliasedExports","migrateAuthorshipDefault","migrateAzureChunkLargeFiles","migrateBlockReferencesToBlocks","migrateBuildScript","migrateDbTypesSubpath","migrateDisabledFields","migrateDocumentTitleContext","migrateFieldComponentTypes","migrateForceSelect","migrateHideAPIURL","migrateImportExportHooks","migrateListViewSelectAPI","migrateNextGenerateViewportExport","migrateNextSubpathExports","migratePayloadRequestCreation","migrateSharpToTransformer","migrateSlugField","migrateStorageAdaptersToConfig","migrateVersionsDefault","removeDefaultLocalePublishOption","removeGroupByTrue","removeLocalizeStatusConfig","removePublishSpecificLocale","removeStorageAlwaysInsertFields","removeVersionsTrue","renameExperimentalTableFeature","renameStorageAdaptersToStorage","renameTypescriptSchemaToJsonSchema","transforms"],"mappings":"AAEA,SAASA,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,WAAW,QAAQ,qCAAoC;AAChE,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,wBAAwB,QAAQ,mDAAkD;AAC3F,SAASC,2BAA2B,QAAQ,wDAAuD;AACnG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,wBAAwB,QAAQ,oDAAmD;AAC5F,SAASC,wBAAwB,QAAQ,qDAAoD;AAC7F,SAASC,iCAAiC,QAAQ,8DAA6D;AAC/G,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,6BAA6B,QAAQ,yDAAwD;AACtG,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,gBAAgB,QAAQ,2CAA0C;AAC3E,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,sBAAsB,QAAQ,iDAAgD;AACvF,SAASC,gCAAgC,QAAQ,6DAA4D;AAC7G,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,+BAA+B,QAAQ,4DAA2D;AAC3G,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,8BAA8B,QAAQ,0DAAyD;AACxG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kCAAkC,QAAQ,gEAA+D;AAElH,OAAO,MAAMC,aAA0B;IACrChC;IACAD;IACAG;IACAW;IACAZ;IACAc;IACAN;IACAG;IACAD;IACAR;IACAe;IACAZ;IACAC;IACAG;IACAS;IACAE;IACAhB;IACAyB;IACAhB;IACAN;IACAQ;IACAC;IACAG;IACAE;IACAlB;IACAmB;IACAC;IACAC;IACAG;IACAF;IACAC;IACAI;IACAF;CACD,CAAA"}
+{"version":3,"sources":["../src/registry.ts"],"sourcesContent":["import type { Transform } from './types.js'\n\nimport { addOverrideAccessTrue } from './transforms/add-override-access-true/index.js'\nimport { exampleNoop } from './transforms/example-noop/index.js'\nimport { globalsComponentsEdit } from './transforms/globals-components-edit/index.js'\nimport { migrateAdminContextProperties } from './transforms/migrate-admin-context-properties/index.js'\nimport { migrateAfterOperationRead } from './transforms/migrate-after-operation-read/index.js'\nimport { migrateAliasedExports } from './transforms/migrate-aliased-exports/index.js'\nimport { migrateAuthorshipDefault } from './transforms/migrate-authorship-default/index.js'\nimport { migrateAzureChunkLargeFiles } from './transforms/migrate-azure-chunk-large-files/index.js'\nimport { migrateBlockReferencesToBlocks } from './transforms/migrate-block-references-to-blocks/index.js'\nimport { migrateBuildScript } from './transforms/migrate-build-script/index.js'\nimport { migrateDbTypesSubpath } from './transforms/migrate-db-types-subpath/index.js'\nimport { migrateDisabledFields } from './transforms/migrate-disabled-fields/index.js'\nimport { migrateDocumentTitleContext } from './transforms/migrate-document-title-context/index.js'\nimport { migrateFieldComponentTypes } from './transforms/migrate-field-component-types/index.js'\nimport { migrateForceSelect } from './transforms/migrate-force-select/index.js'\nimport { migrateHideAPIURL } from './transforms/migrate-hide-api-url/index.js'\nimport { migrateImportExportHooks } from './transforms/migrate-import-export-hooks/index.js'\nimport { migrateListViewSelectAPI } from './transforms/migrate-list-view-select-api/index.js'\nimport { migrateNextGenerateViewportExport } from './transforms/migrate-next-generate-viewport-export/index.js'\nimport { migrateNextSubpathExports } from './transforms/migrate-next-subpath-exports/index.js'\nimport { migratePayloadRequestCreation } from './transforms/migrate-payload-request-creation/index.js'\nimport { migrateSharpToTransformer } from './transforms/migrate-sharp-to-transformer/index.js'\nimport { migrateSlugField } from './transforms/migrate-slug-field/index.js'\nimport { migrateStorageAdaptersToConfig } from './transforms/migrate-storage-adapters-to-config/index.js'\nimport { migrateVersionsDefault } from './transforms/migrate-versions-default/index.js'\nimport { removeDefaultLocalePublishOption } from './transforms/remove-default-locale-publish-option/index.js'\nimport { removeGroupByTrue } from './transforms/remove-group-by-true/index.js'\nimport { removeLocalizeStatusConfig } from './transforms/remove-localize-status-config/index.js'\nimport { removePublishSpecificLocale } from './transforms/remove-publish-specific-locale/index.js'\nimport { removeStorageAlwaysInsertFields } from './transforms/remove-storage-always-insert-fields/index.js'\nimport { removeVersionsTrue } from './transforms/remove-versions-true/index.js'\nimport { renameDiffValueProps } from './transforms/rename-diff-value-props/index.js'\nimport { renameExperimentalTableFeature } from './transforms/rename-experimental-table-feature/index.js'\nimport { renameStorageAdaptersToStorage } from './transforms/rename-storage-adapters-to-storage/index.js'\nimport { renameTypescriptSchemaToJsonSchema } from './transforms/rename-typescript-schema-to-json-schema/index.js'\n\nexport const transforms: Transform[] = [\n  exampleNoop,\n  addOverrideAccessTrue,\n  migrateAfterOperationRead,\n  migrateHideAPIURL,\n  globalsComponentsEdit,\n  migrateListViewSelectAPI,\n  migrateDisabledFields,\n  migrateForceSelect,\n  migrateFieldComponentTypes,\n  renameDiffValueProps,\n  migrateAliasedExports,\n  migratePayloadRequestCreation,\n  migrateAdminContextProperties,\n  migrateBlockReferencesToBlocks,\n  migrateBuildScript,\n  migrateDocumentTitleContext,\n  migrateSharpToTransformer,\n  migrateStorageAdaptersToConfig,\n  migrateAzureChunkLargeFiles,\n  renameStorageAdaptersToStorage,\n  migrateImportExportHooks,\n  migrateDbTypesSubpath,\n  migrateNextGenerateViewportExport,\n  migrateNextSubpathExports,\n  migrateSlugField,\n  migrateVersionsDefault,\n  migrateAuthorshipDefault,\n  removeDefaultLocalePublishOption,\n  removeGroupByTrue,\n  removeLocalizeStatusConfig,\n  removeVersionsTrue,\n  removePublishSpecificLocale,\n  removeStorageAlwaysInsertFields,\n  renameTypescriptSchemaToJsonSchema,\n  renameExperimentalTableFeature,\n]\n"],"names":["addOverrideAccessTrue","exampleNoop","globalsComponentsEdit","migrateAdminContextProperties","migrateAfterOperationRead","migrateAliasedExports","migrateAuthorshipDefault","migrateAzureChunkLargeFiles","migrateBlockReferencesToBlocks","migrateBuildScript","migrateDbTypesSubpath","migrateDisabledFields","migrateDocumentTitleContext","migrateFieldComponentTypes","migrateForceSelect","migrateHideAPIURL","migrateImportExportHooks","migrateListViewSelectAPI","migrateNextGenerateViewportExport","migrateNextSubpathExports","migratePayloadRequestCreation","migrateSharpToTransformer","migrateSlugField","migrateStorageAdaptersToConfig","migrateVersionsDefault","removeDefaultLocalePublishOption","removeGroupByTrue","removeLocalizeStatusConfig","removePublishSpecificLocale","removeStorageAlwaysInsertFields","removeVersionsTrue","renameDiffValueProps","renameExperimentalTableFeature","renameStorageAdaptersToStorage","renameTypescriptSchemaToJsonSchema","transforms"],"mappings":"AAEA,SAASA,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,WAAW,QAAQ,qCAAoC;AAChE,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,6BAA6B,QAAQ,yDAAwD;AACtG,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,wBAAwB,QAAQ,mDAAkD;AAC3F,SAASC,2BAA2B,QAAQ,wDAAuD;AACnG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,wBAAwB,QAAQ,oDAAmD;AAC5F,SAASC,wBAAwB,QAAQ,qDAAoD;AAC7F,SAASC,iCAAiC,QAAQ,8DAA6D;AAC/G,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,6BAA6B,QAAQ,yDAAwD;AACtG,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,gBAAgB,QAAQ,2CAA0C;AAC3E,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,sBAAsB,QAAQ,iDAAgD;AACvF,SAASC,gCAAgC,QAAQ,6DAA4D;AAC7G,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,+BAA+B,QAAQ,4DAA2D;AAC3G,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,oBAAoB,QAAQ,gDAA+C;AACpF,SAASC,8BAA8B,QAAQ,0DAAyD;AACxG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kCAAkC,QAAQ,gEAA+D;AAElH,OAAO,MAAMC,aAA0B;IACrClC;IACAD;IACAI;IACAW;IACAb;IACAe;IACAN;IACAG;IACAD;IACAkB;IACA1B;IACAe;IACAjB;IACAK;IACAC;IACAG;IACAS;IACAE;IACAhB;IACA0B;IACAjB;IACAN;IACAQ;IACAC;IACAG;IACAE;IACAlB;IACAmB;IACAC;IACAC;IACAG;IACAF;IACAC;IACAK;IACAF;CACD,CAAA"}

package/dist/runbook/v4.mdx

@@ -583,6 +583,39 @@ To migrate automatically, there's a codemod for this change available by running
 npx @payloadcms/codemod --transform migrate-field-component-types
 ```
 
+### Diff component props `comparisonValue` and `versionValue` renamed to `valueFrom` and `valueTo`
+
+Custom Diff Components (`admin.components.Diff`) receive the two field values being compared as `valueFrom` and `valueTo`. The `comparisonValue` and `versionValue` props have been removed from `FieldDiffClientProps` and `FieldDiffServerProps`, including every field-specific variant such as `TextFieldDiffClientProps`.
+
+| Old prop          | New prop    | Description                                      |
+| ----------------- | ----------- | ------------------------------------------------ |
+| `comparisonValue` | `valueFrom` | Field value from the version being compared from |
+| `versionValue`    | `valueTo`   | Field value from the version being compared to   |
+
+```diff
+  import type { TextFieldDiffClientProps } from 'payload'
+  import type React from 'react'
+
+  export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
+-   comparisonValue,
+-   versionValue,
++   valueFrom,
++   valueTo,
+  }) => {
+    // ...
+  }
+```
+
+#### Codemod
+
+To migrate automatically, there's a codemod for this change available by running:
+
+```bash
+npx @payloadcms/codemod --transform rename-diff-value-props
+```
+
+The codemod updates functions whose props are typed with a Diff props or component type imported from `payload` (e.g. `TextFieldDiffClientProps`), or with a type in the same file built from one. It renames destructured props and reads such as `props.comparisonValue`. Untyped components and props passed on to other components (e.g. `<OtherDiff comparisonValue={...} />`) aren't changed automatically; the codemod prints a note for each leftover in files that import a Diff type.
+
 ### `DefaultValue` function variant is now typed to allow returning a `Promise` ([#17522](https://github.com/payloadcms/payload/pull/17522))
 
 The exported `DefaultValue` type's function variant previously declared a synchronous-only return type (`SerializableValue`), even though Payload has always awaited the result of a `defaultValue` function at runtime. The type now correctly reflects this and allows `Promise<SerializableValue> | SerializableValue`.
@@ -880,6 +913,49 @@ When a missing locale is already valid for the receiving API, optional chaining
 const locale = useLocale()?.code
 ```
 
+### `readOnly` removed from the `useField` return type
+
+The deprecated `readOnly` property has been removed from `FieldType`, the object returned by `useField`. `useField` already stopped returning it in 3.x, so it was always `undefined` at runtime.
+
+Read `readOnly` from your field component's props instead:
+
+````diff
+'use client'
+import type { TextFieldClientComponent } from 'payload'
+import { useField } from '@payloadcms/ui'
+
+-export const MyField: TextFieldClientComponent = ({ path }) => {
+-  const { readOnly, value } = useField({ path })
++export const MyField: TextFieldClientComponent = ({ path, readOnly }) => {
++  const { value } = useField({ path })
+
+### Deprecated `TableColumnsProvider` props removed
+
+The following deprecated props have been removed from `TableColumnsProvider` and its `TableColumnsProviderProps` type:
+
+- `docs`
+- `enableRowSelections`
+- `listPreferences`
+- `preferenceKey`
+- `renderRowTypes`
+- `setTable`
+- `sortColumnProps`
+- `tableAppearance`
+
+`TableColumnsProvider` has ignored these props since 3.26.0, when column state moved to the URL. Remove them where you render the provider. It now only accepts `children`, `collectionSlug`, `columnState`, and `LinkedCellOverride`.
+
+```diff
+<TableColumnsProvider
+  collectionSlug={collectionSlug}
+  columnState={columnState}
+- enableRowSelections
+- preferenceKey={preferenceKey}
+- tableAppearance="condensed"
+>
+  {children}
+</TableColumnsProvider>
+````
+
 ### RichText adapter `i18n` property removed
 
 The `i18n` property on `RichTextAdapter` (and its return type from adapter provider functions) has been removed. It was deprecated in v3 in favour of merging translations directly into `config.i18n.translations` inside the adapter provider.
@@ -941,6 +1017,52 @@ If an affected adapter or feature performs asynchronous work, move that work to
 
 The `transactionIDPromise` property on `PayloadRequest` has been removed. It was deprecated and unused — `transactionID` (which already supports `Promise<number | string>`) is the correct property to use for both resolved values and pending transactions.
 
+### `headers` and `languageCode` removed from `AdminContext`
+
+The `headers` and `languageCode` properties have been removed from `AdminContext`, the object returned by `initAdminContext`. Both duplicated values that are already available on `req`:
+
+```diff
+const context = await initAdminContext(args)
+
+-const userAgent = context.headers.get('user-agent')
++const userAgent = context.req.headers.get('user-agent')
+
+-const languageCode = context.languageCode
++const languageCode = context.req.i18n.language
+```
+
+`req.i18n.language` is typed as `string`. Cast it to `AcceptedLanguages` if you need the narrower type.
+
+`languageCode` has also been removed from `PartialAdminContext`. Use `i18n.language` instead. `getRootLayoutData` from `@payloadcms/ui` no longer accepts `headers` or `languageCode` and reads both from `req`.
+
+#### Codemod
+
+To migrate automatically, run:
+
+```bash
+npx @payloadcms/codemod --transform migrate-admin-context-properties
+```
+
+The codemod rewrites property reads and destructures on `initAdminContext()` results and on parameters or variables typed as `AdminContext` or `PartialAdminContext`. It also updates `Pick<AdminContext, ...>` and `AdminContext['...']` types and drops both arguments from `getRootLayoutData()` calls. Element access such as `context['headers']`, and contexts passed through your own wrapper functions, are left unchanged for manual migration.
+
+### `DiffMethod` type removed
+
+The deprecated `DiffMethod` type has been removed from `payload`. It mirrored an enum from `react-diff-viewer-continued`, which Payload no longer depends on. Remove any imports of `DiffMethod`.
+
+### `diffMethod` prop removed from Diff components
+
+Custom Diff components (`admin.components.Diff`) no longer receive a `diffMethod` prop. It has been removed from `FieldDiffClientProps` and every field-specific variant like `TextFieldDiffClientProps`. Payload always passed the same `'diffWordsWithSpace'` value, so the prop carried no information. Each Diff component handles its own diffing.
+
+Remove `diffMethod` from your props. If you passed it on to a diffing utility, pass `'diffWordsWithSpace'` directly instead:
+
+```diff
+  export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
+-   diffMethod,
+    valueFrom,
+    valueTo,
+  }) => {
+```
+
 ### Collection `afterOperation` hook: `operation: 'read'` removed
 
 The deprecated `'read'` value for the `operation` argument of collection `afterOperation` hooks has been removed. Payload has not dispatched `afterOperation` with `operation: 'read'` for some time — the `find` and `findByID` operations report their own names (`'find'` and `'findByID'`) instead.
@@ -1050,6 +1172,15 @@ If you use a `declare module` augmentation to extend `GeneratedDatabaseSchema` (
 
 Run `npx @payloadcms/codemod --transform migrate-db-types-subpath` to migrate automatically. The codemod handles import declarations, re-export declarations, and `declare module` augmentations.
 
+### `findMigrationDir` removed from `@payloadcms/drizzle`
+
+The deprecated `findMigrationDir` re-export has been removed from `@payloadcms/drizzle`. Import it from `payload` instead:
+
+```diff
+- import { findMigrationDir } from '@payloadcms/drizzle'
++ import { findMigrationDir } from 'payload'
+```
+
 ### Minimum supported Node.js version is now 24.15.0 ([#16540](https://github.com/payloadcms/payload/pull/16540))
 
 The minimum supported Node.js version is now **24.15.0** (previously 18.20.2). Upgrade your runtime — along with any CI, Docker images, and deployment targets — to the latest node LTS version or newer before upgrading to 4.0.
@@ -1165,6 +1296,43 @@ The table feature is no longer experimental, so it drops its prefix.
 
 Stored content is unaffected.
 
+### Lexical: `LexicalEditorProps` renamed to `LexicalEditorArgs`
+
+The `LexicalEditorProps` type exported from `@payloadcms/richtext-lexical` has been renamed to `LexicalEditorArgs`. It describes the arguments of the `lexicalEditor` function, not component props. The shape is unchanged.
+
+````diff
+- import type { LexicalEditorProps } from '@payloadcms/richtext-lexical'
++ import type { LexicalEditorArgs } from '@payloadcms/richtext-lexical'
+
+### Lexical: `UploadDataImproved` replaced by `UploadData` ([#18606](https://github.com/payloadcms/payload/pull/18606))
+
+The internal `UploadDataImproved` type has been removed, and its definition is now used by the public `UploadData` type. Replace any `UploadDataImproved` imports and type references with `UploadData`:
+
+```ts
+import type { UploadData } from '@payloadcms/richtext-lexical'
+````
+
+### Lexical: the `version` of nodes is ignored
+
+Lexical deprecated the `version` property of serialized nodes, and now ignores it when it loads a document. Payload no longer reads it either.
+
+**Rich text written by the Payload 3.0 betas is no longer upgraded when it's loaded.** Payload used `version: 1` to detect two older shapes:
+
+- Block nodes whose fields were wrapped in an extra `data` object (`fields.data`)
+- Relationship and upload nodes that stored the whole related document in `value`, instead of its ID
+
+If your database may still contain rich text from the 3.0 betas, run `upgradeLexicalData` on the latest 3.x release before you upgrade to 4.0. It re-saves every document, which converts these shapes:
+
+```ts
+import { upgradeLexicalData } from '@payloadcms/richtext-lexical'
+
+await upgradeLexicalData({ payload })
+```
+
+**`version` is optional in the JSON schema of Lexical nodes.** The CLI and MCP no longer require it, and leave it out of the schema they show agents. They still accept it, so existing documents, which contain `version`, stay valid input.
+
+**Payload doesn't add or remove `version` when it saves rich text.** Rich text created by Lexical, like in the admin panel, still has `version: 1` on every node, because Lexical's JSON export writes it. Payload's own nodes used to write their own numbers instead (like `2` for blocks), and now write `1` as well. Rich text sent through the API, CLI or MCP is saved as sent, so it may not contain `version`. The generated types still include `version`, marked as deprecated, so don't rely on it being there.
+
 ### Field `typescriptSchema` renamed to `jsonSchema`
 
 `typescriptSchema` accepted JSON Schema, not TypeScript, so the name lied. Renamed to `jsonSchema`. Same shape, same array of transforms. The underlying schema is now also consumed by the MCP plugin for runtime validation, not just type generation.
@@ -1702,6 +1870,8 @@ If you typed `clientUploads.access`, replace `ClientUploadsAccess` with `UploadI
 
 #### If you maintain a custom storage adapter
 
+File versioning adds a required `GeneratedAdapter.copyFile` method. Copy `from` to `to` (complete storage keys) without changing the source, reject an existing destination, and return only once the destination is readable. `moveFile` stays optional. See [Custom Storage Adapters](../upload/storage-adapters) for the full contract.
+
 Replace `clientUploadContext` with `uploadReference` in generated file metadata and static handler parameters. `handleUpload` no longer receives it because Payload skips uploading files that are already stored.
 
 Set `uploadInstructions.enabled`. When false, Payload adds `adminHandler` to the import map without rendering it. When true, Payload also renders it and exposes the instructions and supporting endpoint.
@@ -1974,6 +2144,12 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
 - Remove `alwaysInsertFields` from your storage adapter or `cloudStoragePlugin` config — it has no effect and no longer exists on the option types.
 - For Postgres, SQLite, or D1 projects, run `payload migrate:create` to generate the migration that adds the `prefix` column, then run `payload migrate` to apply it.
 
+### Upload collections retain originals and file history
+
+Upload collections now store `original` metadata and a `prefix` and `_objectKey` for each stored file (the main file, `original`, and each variant), so saved versions can find their files. New uploads keep their source under an `-original` filename. Update any code or infrastructure that relies on the old filename, URL, or object key.
+
+**Postgres and SQLite:** after updating, run `payload migrate:create`, check that it adds these columns to each upload collection table and its versions table, then run `payload migrate`. Existing rows keep `null` values until their next write.
+
 ### `FileSizeImproved` removed — use `FileSize` ([#16593](https://github.com/payloadcms/payload/pull/16593))
 
 `FileSizeImproved` has been merged into `FileSize`. The `url`, `width`, `height`, `filesize`, `mimeType`, and `filename` properties now accept `null` directly on `FileSize`, matching what the database stores for sizes that were not generated.

package/dist/transforms/migrate-admin-context-properties/basic.input.js

@@ -0,0 +1,32 @@
+import { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData';
+import { initAdminContext } from 'payload/internal';
+export async function getLayoutData(args) {
+    const context = await initAdminContext(args);
+    const { cookies, headers, languageCode, permissions, req, user } = context;
+    const data = await getRootLayoutData({
+        cookies,
+        headers,
+        importMap: args.importMap,
+        languageCode,
+        permissions,
+        req,
+        user
+    });
+    return {
+        data,
+        userAgent: context.headers.get('user-agent')
+    };
+}
+export async function getTheme(args) {
+    const { headers: requestHeaders, languageCode, user } = await initAdminContext(args);
+    return {
+        languageCode,
+        theme: requestHeaders.get('sec-ch-prefers-color-scheme'),
+        user
+    };
+}
+export const getUserAgent = async (args)=>(await initAdminContext(args)).headers.get('user-agent');
+export const getDirection = (context)=>context.languageCode === 'ar' ? 'rtl' : 'ltr';
+export const getAcceptLanguage = ({ headers })=>headers.get('accept-language');
+
+//# sourceMappingURL=basic.input.js.map

package/dist/transforms/migrate-admin-context-properties/basic.input.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/transforms/migrate-admin-context-properties/basic.input.ts"],"sourcesContent":["import type { AdminContext } from 'payload'\nimport type { InitAdminContextArgs } from 'payload/internal'\n\nimport { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData'\nimport { initAdminContext } from 'payload/internal'\n\ntype LayoutArgs = Pick<AdminContext, 'cookies' | 'headers' | 'languageCode' | 'req'>\n\ntype LanguageCode = AdminContext['languageCode']\n\nexport async function getLayoutData(args: InitAdminContextArgs) {\n  const context = await initAdminContext(args)\n\n  const { cookies, headers, languageCode, permissions, req, user } = context\n\n  const data = await getRootLayoutData({\n    cookies,\n    headers,\n    importMap: args.importMap,\n    languageCode,\n    permissions,\n    req,\n    user,\n  })\n\n  return { data, userAgent: context.headers.get('user-agent') }\n}\n\nexport async function getTheme(args: InitAdminContextArgs) {\n  const { headers: requestHeaders, languageCode, user } = await initAdminContext(args)\n\n  return { languageCode, theme: requestHeaders.get('sec-ch-prefers-color-scheme'), user }\n}\n\nexport const getUserAgent = async (args: InitAdminContextArgs) =>\n  (await initAdminContext(args)).headers.get('user-agent')\n\nexport const getDirection = (context: AdminContext) =>\n  context.languageCode === 'ar' ? 'rtl' : 'ltr'\n\nexport const getAcceptLanguage = ({ headers }: AdminContext) => headers.get('accept-language')\n"],"names":["getRootLayoutData","initAdminContext","getLayoutData","args","context","cookies","headers","languageCode","permissions","req","user","data","importMap","userAgent","get","getTheme","requestHeaders","theme","getUserAgent","getDirection","getAcceptLanguage"],"mappings":"AAGA,SAASA,iBAAiB,QAAQ,gDAA+C;AACjF,SAASC,gBAAgB,QAAQ,mBAAkB;AAMnD,OAAO,eAAeC,cAAcC,IAA0B;IAC5D,MAAMC,UAAU,MAAMH,iBAAiBE;IAEvC,MAAM,EAAEE,OAAO,EAAEC,OAAO,EAAEC,YAAY,EAAEC,WAAW,EAAEC,GAAG,EAAEC,IAAI,EAAE,GAAGN;IAEnE,MAAMO,OAAO,MAAMX,kBAAkB;QACnCK;QACAC;QACAM,WAAWT,KAAKS,SAAS;QACzBL;QACAC;QACAC;QACAC;IACF;IAEA,OAAO;QAAEC;QAAME,WAAWT,QAAQE,OAAO,CAACQ,GAAG,CAAC;IAAc;AAC9D;AAEA,OAAO,eAAeC,SAASZ,IAA0B;IACvD,MAAM,EAAEG,SAASU,cAAc,EAAET,YAAY,EAAEG,IAAI,EAAE,GAAG,MAAMT,iBAAiBE;IAE/E,OAAO;QAAEI;QAAcU,OAAOD,eAAeF,GAAG,CAAC;QAAgCJ;IAAK;AACxF;AAEA,OAAO,MAAMQ,eAAe,OAAOf,OACjC,AAAC,CAAA,MAAMF,iBAAiBE,KAAI,EAAGG,OAAO,CAACQ,GAAG,CAAC,cAAa;AAE1D,OAAO,MAAMK,eAAe,CAACf,UAC3BA,QAAQG,YAAY,KAAK,OAAO,QAAQ,MAAK;AAE/C,OAAO,MAAMa,oBAAoB,CAAC,EAAEd,OAAO,EAAgB,GAAKA,QAAQQ,GAAG,CAAC,mBAAkB"}

package/dist/transforms/migrate-admin-context-properties/basic.output.js

@@ -0,0 +1,30 @@
+import { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData';
+import { initAdminContext } from 'payload/internal';
+export async function getLayoutData(args) {
+    const context = await initAdminContext(args);
+    const { cookies, permissions, req, user } = context;
+    const data = await getRootLayoutData({
+        cookies,
+        importMap: args.importMap,
+        permissions,
+        req,
+        user
+    });
+    return {
+        data,
+        userAgent: context.req.headers.get('user-agent')
+    };
+}
+export async function getTheme(args) {
+    const { req: { headers: requestHeaders, i18n: { language: languageCode } }, user } = await initAdminContext(args);
+    return {
+        languageCode,
+        theme: requestHeaders.get('sec-ch-prefers-color-scheme'),
+        user
+    };
+}
+export const getUserAgent = async (args)=>(await initAdminContext(args)).req.headers.get('user-agent');
+export const getDirection = (context)=>context.req.i18n.language === 'ar' ? 'rtl' : 'ltr';
+export const getAcceptLanguage = ({ req: { headers } })=>headers.get('accept-language');
+
+//# sourceMappingURL=basic.output.js.map

package/dist/transforms/migrate-admin-context-properties/basic.output.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/transforms/migrate-admin-context-properties/basic.output.ts"],"sourcesContent":["import type { AdminContext } from 'payload'\nimport type { InitAdminContextArgs } from 'payload/internal'\n\nimport { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData'\nimport { initAdminContext } from 'payload/internal'\n\ntype LayoutArgs = Pick<AdminContext, 'cookies' | 'req'>\n\ntype LanguageCode = AdminContext['req']['i18n']['language']\n\nexport async function getLayoutData(args: InitAdminContextArgs) {\n  const context = await initAdminContext(args)\n\n  const { cookies, permissions, req, user } = context\n\n  const data = await getRootLayoutData({\n    cookies,\n    importMap: args.importMap,\n    permissions,\n    req,\n    user,\n  })\n\n  return { data, userAgent: context.req.headers.get('user-agent') }\n}\n\nexport async function getTheme(args: InitAdminContextArgs) {\n  const { req: { headers: requestHeaders, i18n: { language: languageCode } }, user } = await initAdminContext(args)\n\n  return { languageCode, theme: requestHeaders.get('sec-ch-prefers-color-scheme'), user }\n}\n\nexport const getUserAgent = async (args: InitAdminContextArgs) =>\n  (await initAdminContext(args)).req.headers.get('user-agent')\n\nexport const getDirection = (context: AdminContext) =>\n  context.req.i18n.language === 'ar' ? 'rtl' : 'ltr'\n\nexport const getAcceptLanguage = ({ req: { headers } }: AdminContext) => headers.get('accept-language')\n"],"names":["getRootLayoutData","initAdminContext","getLayoutData","args","context","cookies","permissions","req","user","data","importMap","userAgent","headers","get","getTheme","requestHeaders","i18n","language","languageCode","theme","getUserAgent","getDirection","getAcceptLanguage"],"mappings":"AAGA,SAASA,iBAAiB,QAAQ,gDAA+C;AACjF,SAASC,gBAAgB,QAAQ,mBAAkB;AAMnD,OAAO,eAAeC,cAAcC,IAA0B;IAC5D,MAAMC,UAAU,MAAMH,iBAAiBE;IAEvC,MAAM,EAAEE,OAAO,EAAEC,WAAW,EAAEC,GAAG,EAAEC,IAAI,EAAE,GAAGJ;IAE5C,MAAMK,OAAO,MAAMT,kBAAkB;QACnCK;QACAK,WAAWP,KAAKO,SAAS;QACzBJ;QACAC;QACAC;IACF;IAEA,OAAO;QAAEC;QAAME,WAAWP,QAAQG,GAAG,CAACK,OAAO,CAACC,GAAG,CAAC;IAAc;AAClE;AAEA,OAAO,eAAeC,SAASX,IAA0B;IACvD,MAAM,EAAEI,KAAK,EAAEK,SAASG,cAAc,EAAEC,MAAM,EAAEC,UAAUC,YAAY,EAAE,EAAE,EAAEV,IAAI,EAAE,GAAG,MAAMP,iBAAiBE;IAE5G,OAAO;QAAEe;QAAcC,OAAOJ,eAAeF,GAAG,CAAC;QAAgCL;IAAK;AACxF;AAEA,OAAO,MAAMY,eAAe,OAAOjB,OACjC,AAAC,CAAA,MAAMF,iBAAiBE,KAAI,EAAGI,GAAG,CAACK,OAAO,CAACC,GAAG,CAAC,cAAa;AAE9D,OAAO,MAAMQ,eAAe,CAACjB,UAC3BA,QAAQG,GAAG,CAACS,IAAI,CAACC,QAAQ,KAAK,OAAO,QAAQ,MAAK;AAEpD,OAAO,MAAMK,oBAAoB,CAAC,EAAEf,KAAK,EAAEK,OAAO,EAAE,EAAgB,GAAKA,QAAQC,GAAG,CAAC,mBAAkB"}

package/dist/transforms/migrate-admin-context-properties/index.d.ts

@@ -0,0 +1,3 @@
+import type { Transform } from '../../types.js';
+export declare const migrateAdminContextProperties: Transform;
+//# sourceMappingURL=index.d.ts.map

package/dist/transforms/migrate-admin-context-properties/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transforms/migrate-admin-context-properties/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAwC/C,eAAO,MAAM,6BAA6B,EAAE,SA8J3C,CAAA"}