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

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/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;

package/dist/server/shared/field-traversal/findFieldByPath.js

@@ -0,0 +1,88 @@
+import { classifyField, tabScopes } from "./kernel";
+/**
+ * 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 function findFieldByPath(fields, segments) {
+    const [head, ...rest] = segments;
+    if (head === undefined) return {
+        status: "not-found"
+    };
+    for (const field of fields){
+        const structure = classifyField(field);
+        switch(structure.kind){
+            case "tabs":
+                {
+                    for (const scope of tabScopes(structure.field)){
+                        if (scope.named) {
+                            if (scope.tab.name === head) {
+                                return rest.length === 0 ? {
+                                    status: "container"
+                                } : findFieldByPath(scope.tab.fields, rest);
+                            }
+                        } else {
+                            const found = findFieldByPath(scope.fields, segments); // unnamed tab → same path scope
+                            if (found.status !== "not-found") return found;
+                        }
+                    }
+                    break;
+                }
+            case "transparent":
+                {
+                    const found = findFieldByPath(structure.fields, segments); // row/collapsible/unnamed group → same scope
+                    if (found.status !== "not-found") return found;
+                    break;
+                }
+            case "presentational":
+                break;
+            case "group":
+            case "array":
+                {
+                    if (structure.name !== head) break;
+                    return rest.length === 0 ? {
+                        status: "container"
+                    } : findFieldByPath(structure.fields, rest);
+                }
+            case "blocks":
+                {
+                    if (structure.name !== head) break;
+                    return rest.length === 0 ? {
+                        status: "container"
+                    } : {
+                        status: "inside-blocks"
+                    };
+                }
+            case "leaf":
+                {
+                    if (structure.name !== head) break;
+                    return rest.length === 0 ? {
+                        status: "leaf",
+                        field: structure.field
+                    } : {
+                        status: "not-found"
+                    };
+                }
+            default:
+                {
+                    // Exhaustiveness guard: a new FieldStructure kind would error here at compile time.
+                    const exhaustive = structure;
+                    throw new Error(`unhandled field structure: ${String(exhaustive)}`);
+                }
+        }
+    }
+    return {
+        status: "not-found"
+    };
+}
+
+//# sourceMappingURL=findFieldByPath.js.map

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

@@ -0,0 +1,5 @@
+export { findFieldByPath } from "./findFieldByPath";
+export type { FieldPathResult } from "./findFieldByPath";
+export { classifyField, resolveBlockFields, tabScopes } from "./kernel";
+export type { ChildCursor, ChildOutput, ContainerInfo, FieldStructure, FieldWalker, LeafField, TabScope, WalkSignal } from "./types";
+export { walkFields } from "./walkFields";

package/dist/server/shared/field-traversal/index.js

@@ -0,0 +1,5 @@
+export { findFieldByPath } from "./findFieldByPath";
+export { classifyField, resolveBlockFields, tabScopes } from "./kernel";
+export { walkFields } from "./walkFields";
+
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,85 @@
+import type { BlocksField, Field, TabsField } from "payload";
+import type { FieldStructure, TabScope } from "./types";
+/**
+ * Classify a single Payload {@link Field} into a discriminated {@link FieldStructure} — the
+ * one place that encodes how Payload field types map onto data boundaries.
+ *
+ * Traversals switch on the result instead of re-deriving the predicate chain
+ * (`fieldAffectsData` / `fieldIsGroupType` / …), so the dispatch — and any future Payload
+ * field type — lives in exactly one place.
+ *
+ * @param field - Any field from a collection/global `fields` array (original, un-sanitized
+ * config).
+ * @returns The field's {@link FieldStructure}:
+ * - `tabs` — a `tabs` field (expand with {@link tabScopes}).
+ * - `transparent` — a presentational container that opens **no** data boundary (`row`,
+ *   `collapsible`, unnamed `group`); its `fields` live in the parent's data scope.
+ * - `presentational` — a `ui` field: no data, no subfields.
+ * - `group` / `array` / `blocks` — named data boundaries (carry `name` + child `fields`,
+ *   except `blocks` whose child fields are per-element via {@link resolveBlockFields}).
+ * - `leaf` — a data-affecting field with no subfields.
+ *
+ * Dispatch order is significant: some fields satisfy more than one predicate and only the
+ * order disambiguates them.
+ * - `tabs` is checked first — it carries `.tabs` (not `.fields`) and is non-data-affecting,
+ *   so a later check would mislabel it `presentational`.
+ * - `fieldAffectsData` is resolved before the `group` check, so an unnamed group resolves to
+ *   `transparent`, never a `group` with `name: undefined`.
+ *
+ * @example
+ * ```ts
+ * const structure = classifyField(field);
+ * switch (structure.kind) {
+ *   case "group": descend(structure.fields, data[structure.name]); break;
+ *   case "leaf":  translate(structure.field, structure.name); break;
+ *   // ...handle the remaining kinds
+ * }
+ * ```
+ *
+ * @see {@link walkFields} — the recursive engine built on this classification.
+ * @public
+ */
+export declare function classifyField(field: Field): FieldStructure;
+/**
+ * Flatten a `tabs` field's tabs into {@link TabScope}s, absorbing the named/unnamed +
+ * `hasFields` handling that field traversals would otherwise each repeat.
+ *
+ * @param field - A Payload `tabs` field.
+ * @returns One {@link TabScope} per tab that has fields, in declaration order:
+ * - a **named** tab → `{ named: true, tab }` — it opens a data boundary at `tab.name`, and
+ *   the `NamedTab` is surfaced so callers can read its `name`/`fields`/config;
+ * - an **unnamed** tab → `{ named: false, fields }` — its fields live in the parent's data
+ *   scope, so only the `fields` are needed.
+ *
+ * @example
+ * ```ts
+ * for (const scope of tabScopes(tabsField)) {
+ *   if (scope.named) descendInto(data[scope.tab.name], scope.tab.fields);
+ *   else descendInto(data, scope.fields); // unnamed tab — same data scope as the parent
+ * }
+ * ```
+ * @public
+ */
+export declare function tabScopes(field: TabsField): TabScope[];
+/**
+ * Resolve the child `fields` for a single `blocks` element by matching its `blockType`
+ * against the field's block definitions.
+ *
+ * @param field - A Payload `blocks` field carrying inline block definitions.
+ * @param item - The data for one block element (expected to carry a `blockType` string).
+ * @returns The matched block's `fields`, or `null` when `item` is not a block object or its
+ * `blockType` matches no defined block.
+ *
+ * Assumes the **original, un-sanitized** schema, where blocks are inline `Block` objects on
+ * `field.blocks`. Payload's sanitized config may instead carry `blockReferences` resolved
+ * against the top-level config — not handled here by design, since this package traverses
+ * the original schema to preserve nested `localized` flags.
+ *
+ * @example
+ * ```ts
+ * const fields = resolveBlockFields(blocksField, item);
+ * if (fields) descendInto(item, fields); // null → unknown blockType / not a block → skip
+ * ```
+ * @public
+ */
+export declare function resolveBlockFields(field: BlocksField, item: unknown): Field[] | null;

package/dist/server/shared/field-traversal/kernel.js

@@ -0,0 +1,145 @@
+import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from "payload/shared";
+import { hasFields, isBlockItem, isTabsField } from "../guards";
+/**
+ * Classify a single Payload {@link Field} into a discriminated {@link FieldStructure} — the
+ * one place that encodes how Payload field types map onto data boundaries.
+ *
+ * Traversals switch on the result instead of re-deriving the predicate chain
+ * (`fieldAffectsData` / `fieldIsGroupType` / …), so the dispatch — and any future Payload
+ * field type — lives in exactly one place.
+ *
+ * @param field - Any field from a collection/global `fields` array (original, un-sanitized
+ * config).
+ * @returns The field's {@link FieldStructure}:
+ * - `tabs` — a `tabs` field (expand with {@link tabScopes}).
+ * - `transparent` — a presentational container that opens **no** data boundary (`row`,
+ *   `collapsible`, unnamed `group`); its `fields` live in the parent's data scope.
+ * - `presentational` — a `ui` field: no data, no subfields.
+ * - `group` / `array` / `blocks` — named data boundaries (carry `name` + child `fields`,
+ *   except `blocks` whose child fields are per-element via {@link resolveBlockFields}).
+ * - `leaf` — a data-affecting field with no subfields.
+ *
+ * Dispatch order is significant: some fields satisfy more than one predicate and only the
+ * order disambiguates them.
+ * - `tabs` is checked first — it carries `.tabs` (not `.fields`) and is non-data-affecting,
+ *   so a later check would mislabel it `presentational`.
+ * - `fieldAffectsData` is resolved before the `group` check, so an unnamed group resolves to
+ *   `transparent`, never a `group` with `name: undefined`.
+ *
+ * @example
+ * ```ts
+ * const structure = classifyField(field);
+ * switch (structure.kind) {
+ *   case "group": descend(structure.fields, data[structure.name]); break;
+ *   case "leaf":  translate(structure.field, structure.name); break;
+ *   // ...handle the remaining kinds
+ * }
+ * ```
+ *
+ * @see {@link walkFields} — the recursive engine built on this classification.
+ * @public
+ */ export function classifyField(field) {
+    if (isTabsField(field)) {
+        return {
+            kind: "tabs",
+            field
+        };
+    }
+    if (!fieldAffectsData(field)) {
+        return hasFields(field) ? {
+            kind: "transparent",
+            fields: field.fields
+        } : {
+            kind: "presentational"
+        };
+    }
+    if (fieldIsGroupType(field)) {
+        return {
+            kind: "group",
+            name: field.name,
+            fields: field.fields,
+            field
+        };
+    }
+    if (fieldIsArrayType(field)) {
+        return {
+            kind: "array",
+            name: field.name,
+            fields: field.fields,
+            field
+        };
+    }
+    if (fieldIsBlockType(field)) {
+        return {
+            kind: "blocks",
+            name: field.name,
+            field
+        };
+    }
+    const leaf = field;
+    return {
+        kind: "leaf",
+        name: leaf.name,
+        field: leaf
+    };
+}
+/**
+ * Flatten a `tabs` field's tabs into {@link TabScope}s, absorbing the named/unnamed +
+ * `hasFields` handling that field traversals would otherwise each repeat.
+ *
+ * @param field - A Payload `tabs` field.
+ * @returns One {@link TabScope} per tab that has fields, in declaration order:
+ * - a **named** tab → `{ named: true, tab }` — it opens a data boundary at `tab.name`, and
+ *   the `NamedTab` is surfaced so callers can read its `name`/`fields`/config;
+ * - an **unnamed** tab → `{ named: false, fields }` — its fields live in the parent's data
+ *   scope, so only the `fields` are needed.
+ *
+ * @example
+ * ```ts
+ * for (const scope of tabScopes(tabsField)) {
+ *   if (scope.named) descendInto(data[scope.tab.name], scope.tab.fields);
+ *   else descendInto(data, scope.fields); // unnamed tab — same data scope as the parent
+ * }
+ * ```
+ * @public
+ */ export function tabScopes(field) {
+    const scopes = [];
+    for (const tab of field.tabs){
+        if (tabHasName(tab)) scopes.push({
+            named: true,
+            tab
+        });
+        else if (hasFields(tab)) scopes.push({
+            named: false,
+            fields: tab.fields
+        });
+    }
+    return scopes;
+}
+/**
+ * Resolve the child `fields` for a single `blocks` element by matching its `blockType`
+ * against the field's block definitions.
+ *
+ * @param field - A Payload `blocks` field carrying inline block definitions.
+ * @param item - The data for one block element (expected to carry a `blockType` string).
+ * @returns The matched block's `fields`, or `null` when `item` is not a block object or its
+ * `blockType` matches no defined block.
+ *
+ * Assumes the **original, un-sanitized** schema, where blocks are inline `Block` objects on
+ * `field.blocks`. Payload's sanitized config may instead carry `blockReferences` resolved
+ * against the top-level config — not handled here by design, since this package traverses
+ * the original schema to preserve nested `localized` flags.
+ *
+ * @example
+ * ```ts
+ * const fields = resolveBlockFields(blocksField, item);
+ * if (fields) descendInto(item, fields); // null → unknown blockType / not a block → skip
+ * ```
+ * @public
+ */ export function resolveBlockFields(field, item) {
+    if (!isBlockItem(item)) return null;
+    const block = field.blocks.find((candidate)=>candidate.slug === item.blockType);
+    return block ? block.fields : null;
+}
+
+//# sourceMappingURL=kernel.js.map