@focus-reactive/payload-plugin-translator 0.6.1 → 0.7.0

package/dist/core/content-projection/idPath.js

@@ -0,0 +1,64 @@
+/**
+ * `IdPath` — the stable, location-based identity of a translatable leaf (slice 6 design,
+ * `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`).
+ *
+ * It is the field path from the document root, with one crucial change over a positional path:
+ * **array/blocks element indices are replaced by the element's `id`** (`+ blockType` for blocks),
+ * so the path survives reordering and means the same thing across time. Group/tab/leaf name
+ * segments are unchanged; an element with no `id` falls back to a marked positional segment.
+ *
+ * `idPath` is *where* a piece lives (identity), never *what* it contains — so it can be compared
+ * across time to detect content drift. The whole grammar (escaping, blockType folding, fallback)
+ * lives in {@link makeIdPath}, the sole constructor, so it can never drift.
+ */ const SEP = ".";
+/**
+ * Escape the segment separator, the blockType delimiter, and the positional-fallback marker so
+ * names/ids can't split the path or collide with the "#index" no-id fallback rendered in
+ * {@link renderSegment}.
+ */ const enc = (value)=>value.replace(/[\\#.:]/gu, (c)=>`\\${c}`);
+const renderSegment = (segment)=>{
+    switch(segment.kind){
+        case "key":
+            return enc(segment.name);
+        case "element":
+            return segment.blockType === undefined ? enc(segment.id) : `${enc(segment.id)}:${enc(segment.blockType)}`;
+        case "index":
+            return `#${segment.index}`;
+        default:
+            {
+                const exhaustive = segment;
+                throw new Error(`unhandled path segment: ${String(exhaustive)}`);
+            }
+    }
+};
+/**
+ * The sole constructor of an {@link IdPath}. Renders structural segments to the branded string.
+ */ export function makeIdPath(segments) {
+    return segments.map(renderSegment).join(SEP);
+}
+/**
+ * Build the {@link PathSegment} for one array/blocks element from its data item: keyed by the
+ * element's `id` (with `blockType` folded in for blocks), or a positional fallback when the element
+ * carries no usable `id`.
+ *
+ * @param item - The element's data object.
+ * @param isBlocks - Whether the parent field is a `blocks` field (then `blockType` is folded in).
+ * @param index - Position, used only for the no-id fallback.
+ */ export function elementSegment(item, isBlocks, index) {
+    const { id } = item;
+    if (id === undefined || id === null) return {
+        kind: "index",
+        index
+    };
+    const idStr = String(id);
+    return isBlocks && typeof item.blockType === "string" ? {
+        kind: "element",
+        id: idStr,
+        blockType: item.blockType
+    } : {
+        kind: "element",
+        id: idStr
+    };
+}
+
+//# sourceMappingURL=idPath.js.map

package/dist/core/content-projection/translatableLeaf.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The single definition of "which leaf is translatable, and what its source text is" — shared by
+ * the read-only {@link projectTranslatableContent} (for the provenance fingerprint) and the
+ * translation pipeline's `FieldChunkCollector`, so the two can never disagree on the translatable
+ * set (slice 6 design, option B, `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`).
+ *
+ * Payload-free (structural {@link FieldLike} + owned `Serialized*` views only) so it can move to
+ * `@repo/translator-core` unchanged.
+ */
+import type { FieldLike, LeafFieldLike } from "../field-traversal/types";
+/**
+ * The leaf-SELECTION decision shared by projection and translation: a leaf is a translation target
+ * iff it is a translatable text type, localized, and not excluded via `custom.translateKit`.
+ * Independent of the value present — the value governs whether there is text to emit, not selection.
+ */
+export declare const isTranslatableLeaf: (field: FieldLike | LeafFieldLike) => boolean;
+/**
+ * The shared notion of a leaf's translatable source text, at PROJECTION (field-level) granularity:
+ * - `richText` → the normalized join of its non-empty Lexical text nodes (the same nodes the
+ *   pipeline expands per-node for write-back), trimmed; `null` when it holds no text.
+ * - plain `text`/`textarea` → the trimmed string; `null` when empty or not a string.
+ *
+ * Returns `null` (rather than `""`) for "no translatable text", so callers uniformly skip it.
+ */
+export declare const leafSourceText: (field: {
+    type: string;
+}, value: unknown) => string | null;

package/dist/core/content-projection/translatableLeaf.js

@@ -0,0 +1,37 @@
+/**
+ * The single definition of "which leaf is translatable, and what its source text is" — shared by
+ * the read-only {@link projectTranslatableContent} (for the provenance fingerprint) and the
+ * translation pipeline's `FieldChunkCollector`, so the two can never disagree on the translatable
+ * set (slice 6 design, option B, `docs/plans/2026-06-30-slice6-contentprojector-idpath-design.md`).
+ *
+ * Payload-free (structural {@link FieldLike} + owned `Serialized*` views only) so it can move to
+ * `@repo/translator-core` unchanged.
+ */ import { isFieldExcludedFromTranslation } from "../field-config";
+import { collectSerializedLexicalTextNodes } from "../lexical/collectTextNodes";
+import { isSerializedLexicalRoot } from "../lexical/guards";
+/** The field types this package translates (mirrors `isTranslatableField`, payload-free). */ const isTranslatableFieldType = (field)=>field.type === "text" || field.type === "textarea" || field.type === "richText";
+/** Mirrors `isLocalizedField` structurally. */ const isLocalizedFieldLike = (field)=>field.localized === true;
+/**
+ * The leaf-SELECTION decision shared by projection and translation: a leaf is a translation target
+ * iff it is a translatable text type, localized, and not excluded via `custom.translateKit`.
+ * Independent of the value present — the value governs whether there is text to emit, not selection.
+ */ export const isTranslatableLeaf = (field)=>isTranslatableFieldType(field) && isLocalizedFieldLike(field) && !isFieldExcludedFromTranslation(field);
+/**
+ * The shared notion of a leaf's translatable source text, at PROJECTION (field-level) granularity:
+ * - `richText` → the normalized join of its non-empty Lexical text nodes (the same nodes the
+ *   pipeline expands per-node for write-back), trimmed; `null` when it holds no text.
+ * - plain `text`/`textarea` → the trimmed string; `null` when empty or not a string.
+ *
+ * Returns `null` (rather than `""`) for "no translatable text", so callers uniformly skip it.
+ */ export const leafSourceText = (field, value)=>{
+    if (field.type === "richText") {
+        if (!isSerializedLexicalRoot(value)) return null;
+        const text = collectSerializedLexicalTextNodes(value.root).map((ref)=>ref.node.text).join("").trim();
+        return text.length > 0 ? text : null;
+    }
+    if (typeof value !== "string") return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+};
+
+//# sourceMappingURL=translatableLeaf.js.map

package/dist/core/field-config/getFieldConfig.d.ts

@@ -0,0 +1,23 @@
+import type { FieldTranslationConfig } from "./types";
+/**
+ * Extract translation configuration from a Payload field.
+ *
+ * @param field - The field to extract config from (only its `custom` extension point is read)
+ * @returns The translation configuration, or empty object if not defined
+ */
+export declare function getFieldTranslationConfig(field: {
+    custom?: Record<string, unknown>;
+}): FieldTranslationConfig;
+/**
+ * @deprecated Use `getFieldTranslationConfig` instead
+ */
+export declare const getTranslateKitFieldConfig: typeof getFieldTranslationConfig;
+/**
+ * Check if a field should be excluded from translation.
+ *
+ * @param field - The field to check (only its `custom` extension point is read)
+ * @returns true if the field has `translateKit.exclude: true`
+ */
+export declare function isFieldExcludedFromTranslation(field: {
+    custom?: Record<string, unknown>;
+}): boolean;

package/dist/{server/shared → core}/field-config/getFieldConfig.js

@@ -1,15 +1,15 @@
-import { TRANSLATE_KIT_CUSTOM_KEY } from './types';
+import { TRANSLATE_KIT_CUSTOM_KEY } from "./types";
 /**
  * Extract translation configuration from a Payload field.
  *
- * @param field - The Payload field to extract config from
+ * @param field - The field to extract config from (only its `custom` extension point is read)
  * @returns The translation configuration, or empty object if not defined
  */ export function getFieldTranslationConfig(field) {
-    if (!field.custom || typeof field.custom !== 'object') {
+    if (!field.custom || typeof field.custom !== "object") {
         return {};
     }
     const config = field.custom[TRANSLATE_KIT_CUSTOM_KEY];
-    if (!config || typeof config !== 'object') {
+    if (!config || typeof config !== "object") {
         return {};
     }
     return config;
@@ -20,7 +20,7 @@ import { TRANSLATE_KIT_CUSTOM_KEY } from './types';
 /**
  * Check if a field should be excluded from translation.
  *
- * @param field - The Payload field to check
+ * @param field - The field to check (only its `custom` extension point is read)
  * @returns true if the field has `translateKit.exclude: true`
  */ export function isFieldExcludedFromTranslation(field) {
     return getFieldTranslationConfig(field).exclude === true;

package/dist/{server/shared → core}/field-config/index.d.ts

@@ -1,3 +1,3 @@
-export { getFieldTranslationConfig, getTranslateKitFieldConfig, isFieldExcludedFromTranslation } from './getFieldConfig';
-export { TRANSLATE_KIT_CUSTOM_KEY } from './types';
-export type { FieldTranslationConfig, TranslateKitFieldConfig } from './types';
+export { getFieldTranslationConfig, getTranslateKitFieldConfig, isFieldExcludedFromTranslation, } from "./getFieldConfig";
+export { TRANSLATE_KIT_CUSTOM_KEY } from "./types";
+export type { FieldTranslationConfig, TranslateKitFieldConfig } from "./types";

package/dist/core/field-config/index.js

@@ -0,0 +1,4 @@
+export { getFieldTranslationConfig, getTranslateKitFieldConfig, isFieldExcludedFromTranslation } from "./getFieldConfig";
+export { TRANSLATE_KIT_CUSTOM_KEY } from "./types";
+
+//# sourceMappingURL=index.js.map

package/dist/{server/shared → core}/field-traversal/findFieldByPath.d.ts

@@ -1,5 +1,4 @@
-import type { Field } from "payload";
-import type { LeafField } from "./types";
+import type { FieldLike, LeafField } from "./types";
 /**
  * Outcome of navigating a field schema by a path of segment names (see {@link findFieldByPath}).
  *
@@ -52,4 +51,4 @@ export type FieldPathResult = {
  * @returns A {@link FieldPathResult}.
  * @public
  */
-export declare function findFieldByPath(fields: Field[], segments: string[], data?: unknown): FieldPathResult;
+export declare function findFieldByPath(fields: FieldLike[], segments: string[], data?: unknown): FieldPathResult;

package/dist/core/field-traversal/guards.d.ts

@@ -0,0 +1,19 @@
+import type { FieldLike, TabsFieldLike } from "./types";
+/**
+ * Type guard: Checks if a field is a tabs field.
+ */
+export declare function isTabsField(field: FieldLike): field is TabsFieldLike;
+/**
+ * Type guard: Checks if value is a block item (has blockType property).
+ */
+export declare function isBlockItem(value: unknown): value is Record<string, unknown> & {
+    blockType: string;
+};
+/**
+ * Type guard: Checks if value has a fields array property.
+ * Works with any field/tab-like object; narrows to the framework-agnostic {@link FieldLike}
+ * so the field-traversal kernel that consumes it stays free of Payload types.
+ */
+export declare function hasFields(value: unknown): value is {
+    fields: FieldLike[];
+};

package/dist/core/field-traversal/guards.js

@@ -0,0 +1,20 @@
+import { isObject } from "../utils/isObject";
+/**
+ * Type guard: Checks if a field is a tabs field.
+ */ export function isTabsField(field) {
+    return field.type === "tabs";
+}
+/**
+ * Type guard: Checks if value is a block item (has blockType property).
+ */ export function isBlockItem(value) {
+    return isObject(value) && "blockType" in value && typeof value.blockType === "string";
+}
+/**
+ * Type guard: Checks if value has a fields array property.
+ * Works with any field/tab-like object; narrows to the framework-agnostic {@link FieldLike}
+ * so the field-traversal kernel that consumes it stays free of Payload types.
+ */ export function hasFields(value) {
+    return isObject(value) && "fields" in value && Array.isArray(value.fields);
+}
+
+//# sourceMappingURL=guards.js.map

package/dist/core/field-traversal/index.d.ts

@@ -0,0 +1,7 @@
+export { findFieldByPath } from "./findFieldByPath";
+export type { FieldPathResult } from "./findFieldByPath";
+export { hasFields, isBlockItem, isTabsField } from "./guards";
+export { classifyField, matchElementById, resolveBlockFields, tabScopes } from "./kernel";
+export { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName, } from "./predicates";
+export type { ArrayFieldLike, BlockLike, BlocksFieldLike, ChildCursor, ChildOutput, ContainerInfo, FieldLike, FieldStructure, FieldWalker, GroupFieldLike, LeafField, LeafFieldLike, TabLike, TabScope, TabsFieldLike, WalkSignal, } from "./types";
+export { walkFields } from "./walkFields";

package/dist/core/field-traversal/index.js

@@ -0,0 +1,7 @@
+export { findFieldByPath } from "./findFieldByPath";
+export { hasFields, isBlockItem, isTabsField } from "./guards";
+export { classifyField, matchElementById, resolveBlockFields, tabScopes } from "./kernel";
+export { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from "./predicates";
+export { walkFields } from "./walkFields";
+
+//# sourceMappingURL=index.js.map

package/dist/{server/shared → core}/field-traversal/kernel.d.ts

@@ -1,7 +1,6 @@
-import type { BlocksField, Field, TabsField } from "payload";
-import type { FieldStructure, TabScope } from "./types";
+import type { BlocksFieldLike, FieldLike, FieldStructure, TabScope, TabsFieldLike } from "./types";
 /**
- * Classify a single Payload {@link Field} into a discriminated {@link FieldStructure} — the
+ * Classify a single {@link FieldLike} 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
@@ -39,12 +38,12 @@ import type { FieldStructure, TabScope } from "./types";
  * @see {@link walkFields} — the recursive engine built on this classification.
  * @public
  */
-export declare function classifyField(field: Field): FieldStructure;
+export declare function classifyField(field: FieldLike): 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.
+ * @param field - A {@link TabsFieldLike}.
  * @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;
@@ -60,12 +59,12 @@ export declare function classifyField(field: Field): FieldStructure;
  * ```
  * @public
  */
-export declare function tabScopes(field: TabsField): TabScope[];
+export declare function tabScopes(field: TabsFieldLike): 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 field - A {@link BlocksFieldLike} 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.
@@ -82,7 +81,7 @@ export declare function tabScopes(field: TabsField): TabScope[];
  * ```
  * @public
  */
-export declare function resolveBlockFields(field: BlocksField, item: unknown): Field[] | null;
+export declare function resolveBlockFields(field: BlocksFieldLike, item: unknown): FieldLike[] | null;
 /**
  * Find the element of a parallel data array that corresponds to `refItem` by `id` — not by
  * position.

package/dist/{server/shared → core}/field-traversal/kernel.js

@@ -1,8 +1,8 @@
-import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from "payload/shared";
-import { hasFields, isBlockItem, isTabsField } from "../guards";
-import { isObject } from "../utils";
+import { isObject } from "../utils/isObject";
+import { hasFields, isBlockItem, isTabsField } from "./guards";
+import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from "./predicates";
 /**
- * Classify a single Payload {@link Field} into a discriminated {@link FieldStructure} — the
+ * Classify a single {@link FieldLike} 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
@@ -88,7 +88,7 @@ import { isObject } from "../utils";
  * 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.
+ * @param field - A {@link TabsFieldLike}.
  * @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;
@@ -121,7 +121,7 @@ import { isObject } from "../utils";
  * 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 field - A {@link BlocksFieldLike} 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.

package/dist/core/field-traversal/predicates.d.ts

@@ -0,0 +1,24 @@
+import type { ArrayFieldLike, BlocksFieldLike, FieldLike, GroupFieldLike, TabLike } from "./types";
+/**
+ * Framework-agnostic re-implementations of Payload's field predicates, defined over the
+ * structural {@link FieldLike} family so this traversal layer carries no `payload` import.
+ * Each matches `payload/shared` exactly on every field type (pinned by `predicates.test.ts`);
+ * the parity guard must stay green before the classifier can rely on these.
+ *
+ * @public
+ */
+/** True for an `array` field. Mirrors `payload/shared`'s `fieldIsArrayType`. */
+export declare const fieldIsArrayType: (field: FieldLike) => field is ArrayFieldLike;
+/** True for a `blocks` field. Mirrors `payload/shared`'s `fieldIsBlockType`. */
+export declare const fieldIsBlockType: (field: FieldLike) => field is BlocksFieldLike;
+/** True for a `group` field. Mirrors `payload/shared`'s `fieldIsGroupType`. */
+export declare const fieldIsGroupType: (field: FieldLike) => field is GroupFieldLike;
+/**
+ * True when a field carries data (has a `name`) and is not a presentational `ui` field.
+ * Mirrors `payload/shared`'s `fieldAffectsData`.
+ */
+export declare const fieldAffectsData: (field: FieldLike) => boolean;
+/** True when a tab has a `name` (so it opens a data boundary). Mirrors `payload/shared`'s `tabHasName`. */
+export declare const tabHasName: (tab: TabLike) => tab is TabLike & {
+    name: string;
+};

package/dist/core/field-traversal/predicates.js

@@ -0,0 +1,17 @@
+/**
+ * Framework-agnostic re-implementations of Payload's field predicates, defined over the
+ * structural {@link FieldLike} family so this traversal layer carries no `payload` import.
+ * Each matches `payload/shared` exactly on every field type (pinned by `predicates.test.ts`);
+ * the parity guard must stay green before the classifier can rely on these.
+ *
+ * @public
+ */ /** True for an `array` field. Mirrors `payload/shared`'s `fieldIsArrayType`. */ export const fieldIsArrayType = (field)=>field.type === "array";
+/** True for a `blocks` field. Mirrors `payload/shared`'s `fieldIsBlockType`. */ export const fieldIsBlockType = (field)=>field.type === "blocks";
+/** True for a `group` field. Mirrors `payload/shared`'s `fieldIsGroupType`. */ export const fieldIsGroupType = (field)=>field.type === "group";
+/**
+ * True when a field carries data (has a `name`) and is not a presentational `ui` field.
+ * Mirrors `payload/shared`'s `fieldAffectsData`.
+ */ export const fieldAffectsData = (field)=>"name" in field && field.type !== "ui";
+/** True when a tab has a `name` (so it opens a data boundary). Mirrors `payload/shared`'s `tabHasName`. */ export const tabHasName = (tab)=>"name" in tab;
+
+//# sourceMappingURL=predicates.js.map

package/dist/{server/shared → core}/field-traversal/types.d.ts

@@ -1,16 +1,112 @@
-import type { ArrayField, BlocksField, Field, FieldAffectingData, NamedGroupField, NamedTab, TabAsField, TabsField } from "payload";
+/**
+ * A block definition as this layer needs to read it: a `slug` to match a data element's
+ * `blockType` against, and the child `fields` to descend into. Structurally a superset-compatible
+ * shape of Payload's `Block` (Payload's concrete `Block` is assignable to this).
+ *
+ * @public
+ */
+export interface BlockLike {
+    slug: string;
+    fields: FieldLike[];
+}
+/**
+ * A tab as this layer needs to read it: an optional `name` (present → it opens a data boundary;
+ * absent → it flattens into the parent scope) and its child `fields`. Payload's `Tab`
+ * (`NamedTab | UnnamedTab`) is assignable to this.
+ *
+ * @public
+ */
+export interface TabLike {
+    name?: string;
+    fields: FieldLike[];
+}
+/**
+ * The structural shape of a single field this traversal layer reads — a framework-agnostic
+ * superset that Payload's concrete `Field` union is assignable to. The layer only ever reads
+ * `type` (to classify), `name`/`localized`/`custom` (leaf data + translation config), and the
+ * container members `fields`/`blocks`/`tabs` (to descend). Nothing Payload-specific leaks in.
+ *
+ * @public
+ */
+export interface FieldLike {
+    type: string;
+    name?: string;
+    localized?: boolean;
+    custom?: Record<string, unknown>;
+    fields?: FieldLike[];
+    blocks?: BlockLike[];
+    tabs?: TabLike[];
+}
+/**
+ * A `group` field: a named data boundary whose child `fields` live one level down at `name`.
+ *
+ * @public
+ */
+export interface GroupFieldLike extends FieldLike {
+    type: "group";
+    name: string;
+    fields: FieldLike[];
+}
+/**
+ * An `array` field: a named, repeating data boundary. Its `fields` describe one element; the
+ * data carries N elements keyed by index.
+ *
+ * @public
+ */
+export interface ArrayFieldLike extends FieldLike {
+    type: "array";
+    name: string;
+    fields: FieldLike[];
+}
+/**
+ * A `blocks` field: a named, polymorphic repeating boundary. Each element's child fields are
+ * resolved per element by matching its `blockType` against `blocks[].slug`.
+ *
+ * @public
+ */
+export interface BlocksFieldLike extends FieldLike {
+    type: "blocks";
+    name: string;
+    blocks: BlockLike[];
+}
+/**
+ * A `tabs` field: carries `tabs` (not `fields`) and is non-data-affecting. Expand with
+ * `tabScopes` into named/unnamed {@link TabScope}s.
+ *
+ * @public
+ */
+export interface TabsFieldLike extends FieldLike {
+    type: "tabs";
+    tabs: TabLike[];
+}
 /**
  * A data-affecting field the engine routes to `leaf`: a scalar/relational leaf, never a
- * container (`group`/`array`/`blocks`) and never a `TabAsField`. Narrowing `FieldAffectingData`
- * down to these members is what guarantees `name: string` — the raw union does NOT, because
- * an unnamed `TabAsField` carries `name?: string`.
+ * container (`group`/`array`/`blocks`/`tabs`). The `never` guards on the container members are
+ * what exclude containers — a `FieldLike` carrying `fields`/`blocks`/`tabs` is NOT assignable
+ * here, so leaf dispatch can never silently widen onto a container, and `name` is always present.
+ *
+ * @public
+ */
+export interface LeafFieldLike {
+    name: string;
+    type: string;
+    localized?: boolean;
+    custom?: Record<string, unknown>;
+    fields?: never;
+    blocks?: never;
+    tabs?: never;
+}
+/**
+ * Back-compat alias for {@link LeafFieldLike}. Existing consumers (and `index.ts`) re-export
+ * `LeafField`; the leaf is now defined structurally rather than as a narrowing of Payload's
+ * `FieldAffectingData`.
  *
  * @public
  */
-export type LeafField = Exclude<FieldAffectingData, ArrayField | BlocksField | NamedGroupField | TabAsField>;
+export type LeafField = LeafFieldLike;
 /**
- * Structural classification of a single Payload field — the one place that encodes
- * how Payload field types map onto data boundaries (the dispatch order
+ * Structural classification of a single field — the one place that encodes
+ * how field types map onto data boundaries (the dispatch order
  * `tabs → transparent → group → array → blocks → leaf`).
  *
  * Consumed by {@link FieldWalker}/`walkFields` (the exhaustive, data-parallel walks)
@@ -29,33 +125,33 @@ export type LeafField = Exclude<FieldAffectingData, ArrayField | BlocksField | N
  */
 export type FieldStructure = {
     kind: "tabs";
-    field: TabsField;
+    field: TabsFieldLike;
 } | {
     kind: "transparent";
-    fields: Field[];
+    fields: FieldLike[];
 } | {
     kind: "presentational";
 } | {
     kind: "group";
     name: string;
-    fields: Field[];
-    field: NamedGroupField;
+    fields: FieldLike[];
+    field: GroupFieldLike;
 } | {
     kind: "array";
     name: string;
-    fields: Field[];
-    field: ArrayField;
+    fields: FieldLike[];
+    field: ArrayFieldLike;
 } | {
     kind: "blocks";
     name: string;
-    field: BlocksField;
+    field: BlocksFieldLike;
 } | {
     kind: "leaf";
     name: string;
-    field: LeafField;
+    field: LeafFieldLike;
 };
 /**
- * A tab flattened by `tabScopes`. A named tab opens a data boundary, so its `NamedTab`
+ * A tab flattened by `tabScopes`. A named tab opens a data boundary, so its {@link TabLike}
  * is surfaced (the walker passes it to `enterObject`, and `tab.name` is the data key).
  * An unnamed tab flattens into the parent data scope, so only its `fields` are needed.
  *
@@ -64,10 +160,12 @@ export type FieldStructure = {
  */
 export type TabScope = {
     named: true;
-    tab: NamedTab;
+    tab: TabLike & {
+        name: string;
+    };
 } | {
     named: false;
-    fields: Field[];
+    fields: FieldLike[];
 };
 /**
  * Control signal a walker callback can return instead of descending.
@@ -88,7 +186,7 @@ export type WalkSignal = "skip" | "stop";
 export interface ChildCursor<Cursor extends object> {
     cursor: Cursor;
     /** Child fields to walk under this item. For `blocks`, the resolved `block.fields`. */
-    fields: Field[];
+    fields: FieldLike[];
     /** Index/key this child sits at; surfaced back to `combine`. */
     key: string | number;
 }
@@ -109,15 +207,17 @@ export type ContainerInfo = {
     field: null;
 } | {
     kind: "object";
-    field: NamedGroupField | NamedTab;
+    field: GroupFieldLike | (TabLike & {
+        name: string;
+    });
     key: string;
 } | {
     kind: "list";
-    field: ArrayField | BlocksField;
+    field: ArrayFieldLike | BlocksFieldLike;
     key: string;
 } | {
     kind: "element";
-    field: ArrayField | BlocksField;
+    field: ArrayFieldLike | BlocksFieldLike;
     key: string | number;
 };
 /**
@@ -172,16 +272,18 @@ export interface ChildOutput<Out> {
  */
 export interface FieldWalker<Cursor extends object, Out> {
     /** Enter a single-object boundary (named `group` or named tab). Return the child cursor, or a signal. */
-    enterObject(field: NamedGroupField | NamedTab, cursor: Cursor): Cursor | WalkSignal;
+    enterObject(field: GroupFieldLike | (TabLike & {
+        name: string;
+    }), cursor: Cursor): Cursor | WalkSignal;
     /** Enter an `array`/`blocks` boundary. Return one {@link ChildCursor} per element, or a signal. */
-    enterList(field: ArrayField | BlocksField, cursor: Cursor): ChildCursor<Cursor>[] | WalkSignal;
+    enterList(field: ArrayFieldLike | BlocksFieldLike, cursor: Cursor): ChildCursor<Cursor>[] | WalkSignal;
     /**
-     * Visit a data-affecting leaf. `field` is a {@link LeafField} — the engine has already
+     * Visit a data-affecting leaf. `field` is a {@link LeafFieldLike} — the engine has already
      * resolved it via the `fieldAffectsData` guard and excluded containers/tabs, so `field.name`
-     * is always present and callers never touch the raw `Field` union. Return its output, or
+     * is always present and callers never touch the raw field union. Return its output, or
      * `undefined` to drop it.
      */
-    leaf(field: LeafField, cursor: Cursor): Out | undefined;
+    leaf(field: LeafFieldLike, cursor: Cursor): Out | undefined;
     /**
      * Assemble a container from its children's outputs (called bottom-up). Build-tree
      * callers reconstruct here; collectors return `undefined`. Return `undefined` to drop

package/dist/{server/shared → core}/field-traversal/types.js

@@ -1,4 +1,10 @@
 /**
+ * A block definition as this layer needs to read it: a `slug` to match a data element's
+ * `blockType` against, and the child `fields` to descend into. Structurally a superset-compatible
+ * shape of Payload's `Block` (Payload's concrete `Block` is assignable to this).
+ *
+ * @public
+ */ /**
  * Behaviour a caller plugs into {@link walkFields}. The engine owns structural dispatch and
  * recursion over the **schema**; the caller owns the **data** via the opaque `Cursor`
  * (1..n parallel data trees plus any path live there) and decides what to produce.

package/dist/{server/shared → core}/field-traversal/walkFields.d.ts

@@ -1,5 +1,4 @@
-import type { Field } from "payload";
-import type { FieldWalker } from "./types";
+import type { FieldLike, FieldWalker } from "./types";
 /**
  * Depth-first walk of a Payload field **schema**, driving a caller-supplied
  * {@link FieldWalker}. The single traversal engine this package's data operations build on
@@ -48,4 +47,4 @@ import type { FieldWalker } from "./types";
  * @see {@link FieldWalker} for the full visitor contract and the caller shapes it subsumes.
  * @public
  */
-export declare function walkFields<Cursor extends object, Out>(fields: Field[], root: Cursor, walker: FieldWalker<Cursor, Out>): Out | undefined;
+export declare function walkFields<Cursor extends object, Out>(fields: FieldLike[], root: Cursor, walker: FieldWalker<Cursor, Out>): Out | undefined;