@focus-reactive/payload-plugin-translator 0.4.0 → 0.5.1

package/dist/server/modules/translation-pipeline/stages/data-reconciler/DataReconciler.js

@@ -1,12 +1,70 @@
-import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from 'payload/shared';
-import { hasFields, isBlockItem, isTabsField, isEmpty, isObject } from '../../../../shared';
+import { isEmpty, isObject } from "../../../../shared";
+import { resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+const asObject = (value)=>isObject(value) ? value : {};
 /**
- * Deep merges source and target data with target priority.
- * Creates full document shape needed for Payload validation.
- *
- * Logic:
- * - If targetValue exists and is not empty → use targetValue
- * - Otherwise → use sourceValue
+ * Reconcile walker: produces the full document shape from source + target, with target
+ * priority (source fills empty target slots). Iteration is driven by `source`; a field with
+ * no source value is dropped, `id` is stripped from array/block elements (Postgres rejects it
+ * on update), `blockType` is preserved, and non-object array items / unknown blocks pass
+ * through unchanged.
+ */ const reconcileWalker = {
+    enterObject (field, cursor) {
+        const sourceValue = cursor.source[field.name];
+        if (!isObject(sourceValue)) return "skip"; // undefined / non-object source → drop the field
+        return {
+            source: sourceValue,
+            target: asObject(cursor.target[field.name])
+        };
+    },
+    enterList (field, cursor) {
+        const sourceValue = cursor.source[field.name];
+        if (!Array.isArray(sourceValue)) return "skip";
+        const targetValue = cursor.target[field.name];
+        const targetArr = Array.isArray(targetValue) ? targetValue : [];
+        const children = [];
+        sourceValue.forEach((item, index)=>{
+            if (!isObject(item)) return; // non-object element → passthrough (rebuilt in combine)
+            const fields = field.type === "blocks" ? resolveBlockFields(field, item) : field.fields;
+            if (!fields) return; // unknown blockType → passthrough
+            children.push({
+                cursor: {
+                    source: item,
+                    target: asObject(targetArr[index])
+                },
+                fields,
+                key: index
+            });
+        });
+        return children;
+    },
+    leaf (field, cursor) {
+        const sourceValue = cursor.source[field.name];
+        if (sourceValue === undefined) return undefined; // no source value → field dropped
+        const targetValue = cursor.target[field.name];
+        return isEmpty(targetValue) ? sourceValue : targetValue; // target priority, fallback to source
+    },
+    combine (container, children, cursor) {
+        if (container.kind === "list") {
+            // Rebuild the full array: reconciled objects where present (by index), raw source items otherwise.
+            const sourceArr = cursor.source[container.key] ?? [];
+            const byIndex = new Map(children.map((child)=>[
+                    child.key,
+                    child.out
+                ]));
+            return sourceArr.map((item, index)=>byIndex.has(index) ? byIndex.get(index) : item);
+        }
+        const result = {};
+        for (const child of children)result[child.key] = child.out;
+        // Block elements keep their blockType; id is intentionally stripped (Postgres rejects it on update).
+        if (container.kind === "element" && container.field.type === "blocks") {
+            result.blockType = cursor.source.blockType;
+        }
+        return result;
+    }
+};
+/**
+ * Deep-merges source and target data with target priority, producing the full document shape
+ * Payload validation needs. Built on the shared {@link walkFields} engine.
  *
  * Stage 1 of the translation pipeline.
  */ export class DataReconciler {
@@ -16,81 +74,16 @@ import { hasFields, isBlockItem, isTabsField, isEmpty, isObject } from '../../..
     }
     /**
    * Reconciles source and target data into a complete document shape.
-   * The result contains all fields needed for Payload validation.
    *
    * @param sourceData - Source locale document data
    * @param targetData - Target locale document data (may be empty/partial)
    * @returns Complete document shape with reconciled field values
    */ reconcile(sourceData, targetData) {
-        return this.reconcileFields(this.schema, sourceData, targetData ?? {});
-    }
-    reconcileFields(fields, source, target) {
-        const result = {};
-        for (const field of fields){
-            if (isTabsField(field)) {
-                for (const tab of field.tabs){
-                    if (hasFields(tab)) {
-                        if (tabHasName(tab)) {
-                            const tabSource = source[tab.name];
-                            const tabTarget = target[tab.name];
-                            if (isObject(tabSource)) {
-                                result[tab.name] = this.reconcileFields(tab.fields, tabSource, isObject(tabTarget) ? tabTarget : {});
-                            }
-                        } else {
-                            Object.assign(result, this.reconcileFields(tab.fields, source, target));
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!fieldAffectsData(field)) {
-                if (hasFields(field)) Object.assign(result, this.reconcileFields(field.fields, source, target));
-                continue;
-            }
-            const sourceValue = source[field.name];
-            const targetValue = target[field.name];
-            // Skip undefined source values
-            if (sourceValue === undefined) continue;
-            // Group - recursively reconcile
-            if (fieldIsGroupType(field) && isObject(sourceValue)) {
-                const targetGroup = isObject(targetValue) ? targetValue : {};
-                result[field.name] = this.reconcileFields(field.fields, sourceValue, targetGroup);
-                continue;
-            }
-            // Array - recursively reconcile each item (without id - Postgres rejects it)
-            if (fieldIsArrayType(field) && Array.isArray(sourceValue)) {
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
-                result[field.name] = sourceValue.map((sourceItem, index)=>{
-                    if (isObject(sourceItem)) {
-                        const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                        return this.reconcileFields(field.fields, sourceItem, targetItem);
-                    }
-                    return sourceItem;
-                });
-                continue;
-            }
-            // Blocks - recursively reconcile each block (without id - Postgres rejects it)
-            if (fieldIsBlockType(field) && Array.isArray(sourceValue)) {
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
-                result[field.name] = sourceValue.map((sourceItem, index)=>{
-                    if (isBlockItem(sourceItem)) {
-                        const block = field.blocks.find((b)=>b.slug === sourceItem.blockType);
-                        if (block) {
-                            const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                            return {
-                                ...this.reconcileFields(block.fields, sourceItem, targetItem),
-                                blockType: sourceItem.blockType
-                            };
-                        }
-                    }
-                    return sourceItem;
-                });
-                continue;
-            }
-            // Deep merge: target priority, fallback to source
-            result[field.name] = isEmpty(targetValue) ? sourceValue : targetValue;
-        }
-        return result;
+        const root = {
+            source: sourceData,
+            target: targetData ?? {}
+        };
+        return walkFields(this.schema, root, reconcileWalker) ?? {};
     }
 }
 

package/dist/server/modules/translation-pipeline/stages/field-collector/FieldChunkCollector.d.ts

@@ -1,18 +1,15 @@
-import type { Field } from 'payload';
-import type { FieldChunk } from '../../types';
-import type { TranslationStrategy } from '../../strategies';
+import type { Field } from "payload";
+import type { TranslationStrategy } from "../../strategies";
+import type { FieldChunk } from "../../types";
 /**
- * Collects FieldChunks by traversing schema and data in parallel.
- * Each chunk contains a reference to the parent data object for later mutation.
+ * Collects FieldChunks by walking schema + data with the shared {@link walkFields} engine.
+ * Iteration is driven by `filteredData`; each translatable, localized, non-excluded leaf that
+ * the strategy approves is written with its source value and pushed as a chunk carrying a
+ * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
+ * no-op; results accumulate in a closure.
  *
- * Applies all filtering logic:
- * - isTranslatableField
- * - isLocalizedField
- * - strategy.shouldTranslate(sourceValue, targetValue)
- * - !isFieldExcludedFromTranslation
- *
- * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization).
- * Original schemas preserve `localized: true` on nested fields.
+ * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization). Original
+ * schemas preserve `localized: true` on nested fields.
  */
 export declare class FieldChunkCollector {
     private readonly schema;
@@ -20,15 +17,7 @@ export declare class FieldChunkCollector {
     private readonly sourceData;
     private readonly targetData;
     private readonly strategy;
-    private chunks;
     constructor(schema: Field[], filteredData: Record<string, unknown>, sourceData: Record<string, unknown>, targetData: Record<string, unknown>, strategy: TranslationStrategy);
-    /**
-     * Collects translatable field chunks that need translation.
-     */
+    /** Collects translatable field chunks that need translation. */
     collect(): FieldChunk[];
-    /**
-     * Traverses fields recursively, collecting translatable fields that need translation.
-     * Uses strategy.shouldTranslate() to determine if field needs translation.
-     */
-    private traverseFields;
 }

package/dist/server/modules/translation-pipeline/stages/field-collector/FieldChunkCollector.js

@@ -1,128 +1,107 @@
-import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from 'payload/shared';
-import { hasFields, isBlockItem, isLocalizedField, isObject, isTabsField, isTranslatableField, isFieldExcludedFromTranslation } from '../../../../shared';
+import { isFieldExcludedFromTranslation, isLocalizedField, isObject, isTranslatableField } from "../../../../shared";
+import { resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+const asObject = (value)=>isObject(value) ? value : {};
 /**
- * Collects FieldChunks by traversing schema and data in parallel.
- * Each chunk contains a reference to the parent data object for later mutation.
+ * Collects FieldChunks by walking schema + data with the shared {@link walkFields} engine.
+ * Iteration is driven by `filteredData`; each translatable, localized, non-excluded leaf that
+ * the strategy approves is written with its source value and pushed as a chunk carrying a
+ * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
+ * no-op; results accumulate in a closure.
  *
- * Applies all filtering logic:
- * - isTranslatableField
- * - isLocalizedField
- * - strategy.shouldTranslate(sourceValue, targetValue)
- * - !isFieldExcludedFromTranslation
- *
- * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization).
- * Original schemas preserve `localized: true` on nested fields.
+ * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization). Original
+ * schemas preserve `localized: true` on nested fields.
  */ export class FieldChunkCollector {
     schema;
     filteredData;
     sourceData;
     targetData;
     strategy;
-    chunks;
     constructor(schema, filteredData, sourceData, targetData, strategy){
         this.schema = schema;
         this.filteredData = filteredData;
         this.sourceData = sourceData;
         this.targetData = targetData;
         this.strategy = strategy;
-        this.chunks = [];
-    }
-    /**
-   * Collects translatable field chunks that need translation.
-   */ collect() {
-        this.chunks = [];
-        this.traverseFields(this.schema, this.filteredData, this.sourceData, this.targetData, []);
-        return this.chunks;
     }
-    /**
-   * Traverses fields recursively, collecting translatable fields that need translation.
-   * Uses strategy.shouldTranslate() to determine if field needs translation.
-   */ traverseFields(fields, data, source, target, path) {
-        for (const field of fields){
-            if (isTabsField(field)) {
-                for (const tab of field.tabs){
-                    if (hasFields(tab)) {
-                        if (tabHasName(tab)) {
-                            const tabData = data[tab.name];
-                            const tabSource = source[tab.name];
-                            const tabTarget = target[tab.name];
-                            if (isObject(tabData)) {
-                                this.traverseFields(tab.fields, tabData, isObject(tabSource) ? tabSource : {}, isObject(tabTarget) ? tabTarget : {}, [
-                                    ...path,
-                                    tab.name
-                                ]);
-                            }
-                        } else {
-                            this.traverseFields(tab.fields, data, source, target, path);
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!fieldAffectsData(field)) {
-                if (hasFields(field)) this.traverseFields(field.fields, data, source, target, path);
-                continue;
-            }
-            const value = data[field.name];
-            const sourceValue = source[field.name];
-            const targetValue = target[field.name];
-            if (value === undefined || value === null) continue;
-            const currentPath = [
-                ...path,
-                field.name
-            ];
-            if (fieldIsGroupType(field) && isObject(value)) {
-                this.traverseFields(field.fields, value, isObject(sourceValue) ? sourceValue : {}, isObject(targetValue) ? targetValue : {}, currentPath);
-                continue;
-            }
-            if (fieldIsArrayType(field) && Array.isArray(value)) {
-                const sourceArray = Array.isArray(sourceValue) ? sourceValue : [];
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
+    /** Collects translatable field chunks that need translation. */ collect() {
+        const chunks = [];
+        const { strategy } = this;
+        const walker = {
+            enterObject (field, cursor) {
+                const value = cursor.data[field.name];
+                if (!isObject(value)) return "skip";
+                return {
+                    data: value,
+                    source: asObject(cursor.source[field.name]),
+                    target: asObject(cursor.target[field.name]),
+                    path: [
+                        ...cursor.path,
+                        field.name
+                    ]
+                };
+            },
+            enterList (field, cursor) {
+                const value = cursor.data[field.name];
+                if (!Array.isArray(value)) return "skip";
+                const sourceValue = cursor.source[field.name];
+                const targetValue = cursor.target[field.name];
+                const sourceArr = Array.isArray(sourceValue) ? sourceValue : [];
+                const targetArr = Array.isArray(targetValue) ? targetValue : [];
+                const children = [];
                 value.forEach((item, index)=>{
-                    if (isObject(item)) {
-                        const sourceItem = isObject(sourceArray[index]) ? sourceArray[index] : {};
-                        const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                        this.traverseFields(field.fields, item, sourceItem, targetItem, [
-                            ...currentPath,
-                            String(index)
-                        ]);
-                    }
-                });
-                continue;
-            }
-            if (fieldIsBlockType(field) && Array.isArray(value)) {
-                const sourceArray = Array.isArray(sourceValue) ? sourceValue : [];
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
-                value.forEach((item, index)=>{
-                    if (isBlockItem(item)) {
-                        const block = field.blocks.find((b)=>b.slug === item.blockType);
-                        if (block) {
-                            const sourceItem = isObject(sourceArray[index]) ? sourceArray[index] : {};
-                            const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                            this.traverseFields(block.fields, item, sourceItem, targetItem, [
-                                ...currentPath,
+                    if (!isObject(item)) return;
+                    const fields = field.type === "blocks" ? resolveBlockFields(field, item) : field.fields;
+                    if (!fields) return; // unknown blockType → skip element
+                    children.push({
+                        cursor: {
+                            data: item,
+                            source: asObject(sourceArr[index]),
+                            target: asObject(targetArr[index]),
+                            path: [
+                                ...cursor.path,
+                                field.name,
                                 String(index)
-                            ]);
-                        }
-                    }
-                });
-                continue;
-            }
-            // Collect if: translatable, localized, not excluded, and strategy says to translate
-            if (isTranslatableField(field) && isLocalizedField(field) && !isFieldExcludedFromTranslation(field) && this.strategy.shouldTranslate({
-                sourceValue,
-                targetValue
-            })) {
-                // Write sourceValue to filteredData — this is what will be translated
-                data[field.name] = sourceValue;
-                this.chunks.push({
-                    schema: field,
-                    dataRef: data,
-                    key: field.name,
-                    path: currentPath
+                            ]
+                        },
+                        fields,
+                        key: index
+                    });
                 });
+                return children;
+            },
+            leaf (field, cursor) {
+                const value = cursor.data[field.name];
+                if (value === undefined || value === null) return undefined;
+                const sourceValue = cursor.source[field.name];
+                const targetValue = cursor.target[field.name];
+                if (isTranslatableField(field) && isLocalizedField(field) && !isFieldExcludedFromTranslation(field) && strategy.shouldTranslate({
+                    sourceValue,
+                    targetValue
+                })) {
+                    cursor.data[field.name] = sourceValue; // write source value into filteredData — this is what gets translated
+                    chunks.push({
+                        schema: field,
+                        dataRef: cursor.data,
+                        key: field.name,
+                        path: [
+                            ...cursor.path,
+                            field.name
+                        ]
+                    });
+                }
+                return undefined;
+            },
+            combine () {
+                return undefined; // collect-only — nothing to assemble
             }
-        }
+        };
+        walkFields(this.schema, {
+            data: this.filteredData,
+            source: this.sourceData,
+            target: this.targetData,
+            path: []
+        }, walker);
+        return chunks;
     }
 }
 

package/dist/server/modules/translation-pipeline/translateContent.d.ts

@@ -0,0 +1,35 @@
+import type { Field } from "payload";
+import type { TranslationProvider } from "../translation-providers";
+import type { TranslationStrategyName } from "./strategies";
+export type TranslateContentArgs = {
+    /** Schema subtree to translate (e.g. `[declaredFieldConfig]`). */
+    schema: Field[];
+    /** Source values, rooted to match `schema` (e.g. `{ [fieldName]: value }`). */
+    sourceData: Record<string, unknown>;
+    /**
+     * Existing target-locale values to reconcile against (target wins when
+     * non-empty under `skip_existing`). Defaults to `{}` — i.e. translate the
+     * source in place (`overwrite`).
+     */
+    targetData?: Record<string, unknown>;
+    /** Source language code, or `''` for provider auto-detect. */
+    sourceLng: string;
+    targetLng: string;
+    translationProvider: TranslationProvider;
+    /** @default 'overwrite' */
+    strategy?: TranslationStrategyName;
+};
+/**
+ * Translate a content object over a schema subtree — no DB, no document.
+ *
+ * A thin reusable entry over {@link TranslationPipeline}, which is already pure
+ * and walks any `Field[]` + matching data (a subtree + partial data works
+ * unchanged). The document level routes through this wrapper today (instead of
+ * constructing the pipeline inline); the upcoming field level will too —
+ * passing a single declared field's subtree + its current unsaved form value.
+ *
+ * Only `localized` text/richText leaves are translated; non-localized values
+ * are reconciled through unchanged. Returns the translated data (same shape as
+ * `sourceData`) or `null` when nothing was translatable.
+ */
+export declare function translateContent({ schema, sourceData, targetData, sourceLng, targetLng, translationProvider, strategy, }: TranslateContentArgs): Promise<Record<string, unknown> | null>;

package/dist/server/modules/translation-pipeline/translateContent.js

@@ -0,0 +1,30 @@
+import { TranslationPipeline } from "./TranslationPipeline";
+import { createTranslationStrategy } from "./strategies";
+/**
+ * Translate a content object over a schema subtree — no DB, no document.
+ *
+ * A thin reusable entry over {@link TranslationPipeline}, which is already pure
+ * and walks any `Field[]` + matching data (a subtree + partial data works
+ * unchanged). The document level routes through this wrapper today (instead of
+ * constructing the pipeline inline); the upcoming field level will too —
+ * passing a single declared field's subtree + its current unsaved form value.
+ *
+ * Only `localized` text/richText leaves are translated; non-localized values
+ * are reconciled through unchanged. Returns the translated data (same shape as
+ * `sourceData`) or `null` when nothing was translatable.
+ */ export async function translateContent({ schema, sourceData, targetData = {}, sourceLng, targetLng, translationProvider, strategy = "overwrite" }) {
+    const pipeline = new TranslationPipeline({
+        translationProvider,
+        translationStrategy: createTranslationStrategy(strategy)
+    });
+    const result = await pipeline.execute({
+        schema,
+        sourceData,
+        targetData,
+        sourceLng,
+        targetLng
+    });
+    return result ? result.translatedData : null;
+}
+
+//# sourceMappingURL=translateContent.js.map

package/dist/server/modules/translation-providers/OpenAITranslation.provider.d.ts

@@ -1,5 +1,5 @@
-import type { TranslationProvider, TranslationInput, TranslationOutput } from './TranslationProvider.interface';
-import type { ChatModel } from 'openai/resources/index.mjs';
+import type { TranslationProvider, TranslationInput, TranslationOutput } from "./TranslationProvider.interface";
+import type { ChatModel } from "openai/resources/index.mjs";
 /**
  * Function to transform text in dry run mode.
  * Receives the original text and returns the transformed text.
@@ -30,6 +30,7 @@ export type SystemPromptContext = {
  */
 type SystemPromptBuilder = (context: SystemPromptContext) => string;
 export type OpenAIProviderConfig = {
+    /** OpenAI API key (required). Read it from an env var — never hard-code it. */
     apiKey: string;
     /**
      * OpenAI model to use for translation.
@@ -78,8 +79,8 @@ export type OpenAIProviderConfig = {
 };
 /** @deprecated Use `createOpenAIProvider` function instead */
 export declare class OpenAITranslationProvider implements TranslationProvider {
-    private readonly config;
     private openAiClient;
+    private readonly config;
     constructor(config: OpenAIProviderConfig);
     translate(content: TranslationInput, souceLng: string, targetLng: string): Promise<TranslationOutput | null>;
     /**

package/dist/server/modules/translation-providers/OpenAITranslation.provider.js

@@ -1,21 +1,21 @@
-import OpenAI from 'openai';
-import { isObject } from '../../shared';
+import OpenAI from "openai";
+import { isObject } from "../../shared";
 /** @deprecated Use `createOpenAIProvider` function instead */ export class OpenAITranslationProvider {
-    config;
     openAiClient;
+    config;
     constructor(config){
-        this.config = config;
         this.openAiClient = new OpenAI({
             apiKey: config.apiKey
         });
+        this.config = config;
     }
     async translate(content, souceLng, targetLng) {
         if (this.config.dryRun) {
-            console.info('[DRY RUN] Translation simulation:', {
+            console.info("[DRY RUN] Translation simulation:", {
                 content,
                 sourceLang: souceLng,
                 targetLang: targetLng,
-                provider: 'OpenAI'
+                provider: "OpenAI"
             });
             const timeout = this.getDryRunTimeout();
             if (timeout > 0) await new Promise((resolve)=>setTimeout(resolve, timeout));
@@ -26,21 +26,21 @@ import { isObject } from '../../shared';
         const chatCompletion = await this.openAiClient.chat.completions.create({
             messages: [
                 {
-                    role: 'system',
+                    role: "system",
                     content: systemPrompt
                 },
                 {
-                    role: 'user',
+                    role: "user",
                     content: JSON.stringify(content)
                 }
             ],
-            model: this.config.model ?? 'gpt-4o',
+            model: this.config.model ?? "gpt-4o",
             temperature: 0,
             top_p: 1,
             frequency_penalty: 0,
             presence_penalty: 0,
             response_format: {
-                type: 'json_object'
+                type: "json_object"
             }
         });
         const translatedContent = chatCompletion.choices[0].message.content;
@@ -54,7 +54,7 @@ import { isObject } from '../../shared';
     /**
    * Builds the system prompt for translation.
    */ buildSystemPrompt(sourceLang, targetLang) {
-        const defaultPrompt = `Translate the values from the JSON that the user will send you${sourceLang ? ` from ${sourceLang}` : ''} into ${targetLang}. Keep all JSON keys exactly as they are, only translate the values.
+        const defaultPrompt = `Translate the values from the JSON that the user will send you${sourceLang ? ` from ${sourceLang}` : ""} into ${targetLang}. Keep all JSON keys exactly as they are, only translate the values.
 The response should be a valid JSON object with the same structure and keys as the input, but with translated values.
 Maintain any special formatting, placeholders, or variables within the values if they exist.`;
         if (this.config.systemPrompt) {
@@ -71,17 +71,17 @@ Maintain any special formatting, placeholders, or variables within the values if
    * If dryRun is an object with transform, returns it.
    * If dryRun is true, returns the default transformer that reverses text.
    */ getDryRunTransformer() {
-        if (typeof this.config.dryRun === 'object' && this.config.dryRun.transform) {
+        if (typeof this.config.dryRun === "object" && this.config.dryRun.transform) {
             return this.config.dryRun.transform;
         }
-        return (text)=>text.split('').reverse().join('');
+        return (text)=>text.split("").reverse().join("");
     }
     /**
    * Returns the timeout for dry run mode.
    * If dryRun is an object with timeout, returns it.
    * Otherwise returns 0 (no delay).
    */ getDryRunTimeout() {
-        if (typeof this.config.dryRun === 'object' && this.config.dryRun.timeout) {
+        if (typeof this.config.dryRun === "object" && this.config.dryRun.timeout) {
             return this.config.dryRun.timeout;
         }
         return 0;
@@ -89,7 +89,7 @@ Maintain any special formatting, placeholders, or variables within the values if
     async createMockTranslation(content, transformer) {
         try {
             const mockTranslation = await this.transformObjectValues(content, async (value)=>{
-                if (typeof value === 'string' && value.trim()) return transformer(value);
+                if (typeof value === "string" && value.trim()) return transformer(value);
                 return value;
             });
             return mockTranslation;

package/dist/server/shared/field-traversal/findFieldByPath.d.ts

@@ -0,0 +1,40 @@
+import type { Field } from "payload";
+import type { LeafField } from "./types";
+/**
+ * Outcome of navigating a field schema by a path of segment names (see {@link findFieldByPath}).
+ *
+ * - `leaf` — the path lands on a data-affecting leaf field (carries it).
+ * - `container` — the path lands on a `group`/`array`/`blocks` field or a named tab (a container,
+ *   not a leaf).
+ * - `inside-blocks` — the path descends THROUGH a `blocks` field, which can't be resolved from the
+ *   schema alone (the block's `blockType` lives in the data, not the schema).
+ * - `not-found` — no field matches a segment, or the path continues past a leaf.
+ *
+ * @public
+ */
+export type FieldPathResult = {
+    status: "leaf";
+    field: LeafField;
+} | {
+    status: "container";
+} | {
+    status: "inside-blocks";
+} | {
+    status: "not-found";
+};
+/**
+ * Navigate a field schema by a path of segment NAMES, descending one matching branch at a time
+ * with early-exit (targeted navigation, not an exhaustive walk). Presentational containers
+ * (`row`/`collapsible`/unnamed `group`) and unnamed tabs are transparent — searched in the same
+ * path scope. Built on {@link classifyField} / {@link tabScopes} so the structural dispatch lives
+ * in one place.
+ *
+ * The caller supplies already-prepared name segments (split, trimmed, with array indices dropped —
+ * a field's config is shared across array items, so indices never appear in the schema).
+ *
+ * @param fields - The schema level to search.
+ * @param segments - Remaining path segments (names) to match, head-first.
+ * @returns A {@link FieldPathResult}.
+ * @public
+ */
+export declare function findFieldByPath(fields: Field[], segments: string[]): FieldPathResult;