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

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

@@ -0,0 +1,133 @@
+import { classifyField, resolveBlockFields, tabScopes } from "./kernel";
+const isIndexSegment = (segment)=>/^\d+$/u.test(segment);
+/** Safely read `key` off an object/array; `undefined` for non-objects (arrays index by string key). */ const childData = (data, key)=>data != null && typeof data === "object" ? data[key] : undefined;
+/**
+ * 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} / {@link resolveBlockFields} so
+ * the structural dispatch lives in one place.
+ *
+ * **Array indices and `blocks`.** Array element configs are shared, so a numeric segment after an
+ * array name selects the data item but not the schema (the schema continues into `array.fields`).
+ * A `blocks` field is polymorphic — which block (and thus which fields) sits at an index lives in
+ * the *data*, not the schema. So to descend through `blocks` the caller must pass the document
+ * `data` and keep the element index in the path: this function reads `data[name][index].blockType`
+ * and resolves the matching block via {@link resolveBlockFields}. Without `data` (or with a
+ * non-indexed path), descending through `blocks` returns `inside-blocks`.
+ *
+ * @param fields - The schema level to search.
+ * @param segments - Remaining path segments to match, head-first. Keep array/block element indices
+ *   in the path when navigating with `data`.
+ * @param data - The document (sub)tree aligned with `fields`, used only to disambiguate `blocks`.
+ *   Omit for schema-only navigation.
+ * @returns A {@link FieldPathResult}.
+ * @public
+ */ export function findFieldByPath(fields, segments, data) {
+    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, childData(data, head));
+                            }
+                        } else {
+                            const found = findFieldByPath(scope.fields, segments, data); // unnamed tab → same path + data scope
+                            if (found.status !== "not-found") return found;
+                        }
+                    }
+                    break;
+                }
+            case "transparent":
+                {
+                    const found = findFieldByPath(structure.fields, segments, data); // row/collapsible/unnamed group → same scope
+                    if (found.status !== "not-found") return found;
+                    break;
+                }
+            case "presentational":
+                break;
+            case "group":
+                {
+                    if (structure.name !== head) break;
+                    return rest.length === 0 ? {
+                        status: "container"
+                    } : findFieldByPath(structure.fields, rest, childData(data, head));
+                }
+            case "array":
+                {
+                    if (structure.name !== head) break;
+                    if (rest.length === 0) return {
+                        status: "container"
+                    };
+                    // A localized array is an independent per-locale structure — its element index is not a
+                    // stable identity across locales, so refuse to navigate THROUGH it by path.
+                    if (structure.field.localized) return {
+                        status: "localized-list-ancestor"
+                    };
+                    // A numeric segment selects the data element; the schema is shared across elements.
+                    const [next, ...tail] = rest;
+                    if (isIndexSegment(next)) {
+                        return tail.length === 0 ? {
+                            status: "container"
+                        } : findFieldByPath(structure.fields, tail, childData(childData(data, head), next));
+                    }
+                    return findFieldByPath(structure.fields, rest, childData(data, head));
+                }
+            case "blocks":
+                {
+                    if (structure.name !== head) break;
+                    if (rest.length === 0) return {
+                        status: "container"
+                    };
+                    // A localized blocks field is an independent per-locale structure — its element index is
+                    // not a stable identity across locales, so refuse to navigate THROUGH it by path.
+                    if (structure.field.localized) return {
+                        status: "localized-list-ancestor"
+                    };
+                    // Polymorphic: need the element index + its data to pick the block schema by `blockType`.
+                    const [next, ...tail] = rest;
+                    if (!isIndexSegment(next)) return {
+                        status: "inside-blocks"
+                    };
+                    const item = childData(childData(data, head), next);
+                    const blockFields = resolveBlockFields(structure.field, item);
+                    if (!blockFields) return {
+                        status: "inside-blocks"
+                    };
+                    return tail.length === 0 ? {
+                        status: "container"
+                    } : findFieldByPath(blockFields, tail, item);
+                }
+            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, matchElementById, 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, matchElementById, resolveBlockFields, tabScopes } from "./kernel";
+export { walkFields } from "./walkFields";
+
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,107 @@
+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;
+/**
+ * Find the element of a parallel data array that corresponds to `refItem` by `id` — not by
+ * position.
+ *
+ * Localized `blocks`/`array` fields are stored independently per locale, so the locales can be
+ * reordered or differ entirely; pairing two parallel trees by position then cross-contaminates
+ * unrelated elements ("blocks don't line up across locales"). Matching by `id` is correct in both
+ * regimes: a non-localized field is one shared row with the same `id` across locales (so id-match
+ * equals the old positional match), while independent localized content has diverging ids (no
+ * match → the caller falls back to `refItem`'s own values, never another element's). For blocks the
+ * `blockType` must also match, so an id collision across types can't graft mismatched fields.
+ *
+ * Shared by the translation pipeline's two multi-tree walkers — reconcile and collect — to pair
+ * their `target` array against the source/reference element currently being visited.
+ *
+ * @param arr - The array to search (e.g. the target-locale elements).
+ * @param refItem - The element being matched, carrying the canonical `id` (and `blockType`).
+ * @param isBlocks - Whether the field is a `blocks` field (then `blockType` must also match).
+ * @returns The matched element, or `{}` when there is no counterpart (or `refItem` carries no `id`).
+ * @public
+ */
+export declare function matchElementById(arr: unknown[], refItem: Record<string, unknown>, isBlocks: boolean): Record<string, unknown>;

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

@@ -0,0 +1,172 @@
+import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from "payload/shared";
+import { hasFields, isBlockItem, isTabsField } from "../guards";
+import { isObject } from "../utils";
+/**
+ * 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;
+}
+/**
+ * Find the element of a parallel data array that corresponds to `refItem` by `id` — not by
+ * position.
+ *
+ * Localized `blocks`/`array` fields are stored independently per locale, so the locales can be
+ * reordered or differ entirely; pairing two parallel trees by position then cross-contaminates
+ * unrelated elements ("blocks don't line up across locales"). Matching by `id` is correct in both
+ * regimes: a non-localized field is one shared row with the same `id` across locales (so id-match
+ * equals the old positional match), while independent localized content has diverging ids (no
+ * match → the caller falls back to `refItem`'s own values, never another element's). For blocks the
+ * `blockType` must also match, so an id collision across types can't graft mismatched fields.
+ *
+ * Shared by the translation pipeline's two multi-tree walkers — reconcile and collect — to pair
+ * their `target` array against the source/reference element currently being visited.
+ *
+ * @param arr - The array to search (e.g. the target-locale elements).
+ * @param refItem - The element being matched, carrying the canonical `id` (and `blockType`).
+ * @param isBlocks - Whether the field is a `blocks` field (then `blockType` must also match).
+ * @returns The matched element, or `{}` when there is no counterpart (or `refItem` carries no `id`).
+ * @public
+ */ export function matchElementById(arr, refItem, isBlocks) {
+    const id = refItem.id;
+    if (id === undefined || id === null) return {};
+    const match = arr.find((candidate)=>isObject(candidate) && candidate.id === id && (!isBlocks || candidate.blockType === refItem.blockType));
+    return isObject(match) ? match : {};
+}
+
+//# sourceMappingURL=kernel.js.map

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

@@ -0,0 +1,191 @@
+import type { ArrayField, BlocksField, Field, FieldAffectingData, NamedGroupField, NamedTab, TabAsField, TabsField } from "payload";
+/**
+ * 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`.
+ *
+ * @public
+ */
+export type LeafField = Exclude<FieldAffectingData, ArrayField | BlocksField | NamedGroupField | TabAsField>;
+/**
+ * Structural classification of a single Payload field — the one place that encodes
+ * how Payload 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)
+ * and by path-navigation; the four hand-rolled traversals collapse onto it so the
+ * dispatch lives in exactly one place.
+ *
+ * - `transparent` — presentational container that does NOT open a data boundary
+ *   (row, collapsible, unnamed group). Its `fields` live in the SAME data scope as
+ *   the parent.
+ * - `presentational` — a `ui` leaf: no data, no subfields.
+ * - `group`/`array`/`blocks` — open a data boundary at `name`.
+ * - `leaf` — a data-affecting field with no subfields.
+ *
+ * @see {@link classifyField} — produces this; {@link walkFields} — consumes it.
+ * @public
+ */
+export type FieldStructure = {
+    kind: "tabs";
+    field: TabsField;
+} | {
+    kind: "transparent";
+    fields: Field[];
+} | {
+    kind: "presentational";
+} | {
+    kind: "group";
+    name: string;
+    fields: Field[];
+    field: NamedGroupField;
+} | {
+    kind: "array";
+    name: string;
+    fields: Field[];
+    field: ArrayField;
+} | {
+    kind: "blocks";
+    name: string;
+    field: BlocksField;
+} | {
+    kind: "leaf";
+    name: string;
+    field: LeafField;
+};
+/**
+ * A tab flattened by `tabScopes`. A named tab opens a data boundary, so its `NamedTab`
+ * 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.
+ *
+ * @see {@link tabScopes}
+ * @public
+ */
+export type TabScope = {
+    named: true;
+    tab: NamedTab;
+} | {
+    named: false;
+    fields: Field[];
+};
+/**
+ * Control signal a walker callback can return instead of descending.
+ * - `skip` — do not descend this branch; continue with siblings.
+ * - `stop` — halt the whole walk (used for path-style navigation / early-exit).
+ *
+ * @public
+ */
+export type WalkSignal = "skip" | "stop";
+/**
+ * One child to recurse under an array/blocks boundary. The caller derives these from its own
+ * data (it alone knows how many elements there are and their shape) and returns them from
+ * {@link FieldWalker.enterList}.
+ *
+ * @template Cursor - The walker's data-position type (see {@link FieldWalker}).
+ * @public
+ */
+export interface ChildCursor<Cursor extends object> {
+    cursor: Cursor;
+    /** Child fields to walk under this item. For `blocks`, the resolved `block.fields`. */
+    fields: Field[];
+    /** Index/key this child sits at; surfaced back to `combine`. */
+    key: string | number;
+}
+/**
+ * The container the engine asks the walker to assemble, bottom-up.
+ *
+ * - `root` — the top-level field list (`field` is `null`).
+ * - `object` — a `group` or a named tab.
+ * - `list` — an `array` or `blocks` collection (children are its elements, keyed by index).
+ * - `element` — a single element of a list (children are its fields). `field` is the
+ *   parent list field; distinguish array vs blocks via `field.type`.
+ *
+ * @see {@link FieldWalker.combine}
+ * @public
+ */
+export type ContainerInfo = {
+    kind: "root";
+    field: null;
+} | {
+    kind: "object";
+    field: NamedGroupField | NamedTab;
+    key: string;
+} | {
+    kind: "list";
+    field: ArrayField | BlocksField;
+    key: string;
+} | {
+    kind: "element";
+    field: ArrayField | BlocksField;
+    key: string | number;
+};
+/**
+ * A child's assembled output, tagged with the key it sat at within its parent. Passed to
+ * {@link FieldWalker.combine} as the `children` list.
+ *
+ * @template Out - The walker's per-node output type (see {@link FieldWalker}).
+ * @public
+ */
+export interface ChildOutput<Out> {
+    key: string | number;
+    out: Out;
+}
+/**
+ * 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.
+ *
+ * Shapes this is designed to subsume (one engine, many callers):
+ * - build-tree (filter / reconcile) — reconstruct values in `combine`.
+ * - collect + mutate (field-chunk collector) — push/mutate in `leaf`, `combine` is a no-op.
+ * - navigate + early-exit (path resolver) — `enter*` returns `'skip'`/`'stop'`.
+ *
+ * @template Cursor - The data position threaded through the walk. The engine never reads it;
+ * it only passes it to your callbacks and stores the cursors you return. Constrained to
+ * `object` so a cursor can never collide with a {@link WalkSignal} string (`'skip'`/`'stop'`).
+ * @template Out - What you produce per leaf and assemble per container. Use `void` for a
+ * collect-only walk (accumulate in a closure, return `undefined` from `combine`).
+ *
+ * @example
+ * A collect-only walker that records the path of every localized leaf:
+ * ```ts
+ * type Cursor = { data: Record<string, unknown>; path: string[] };
+ * const found: string[] = [];
+ *
+ * const walker: FieldWalker<Cursor, void> = {
+ *   enterObject: (field, c) =>
+ *     isRecord(c.data[field.name])
+ *       ? { data: c.data[field.name], path: [...c.path, field.name] }
+ *       : "skip",
+ *   enterList: (field, c) => toItemCursors(field, c),
+ *   leaf: (field, c) => {
+ *     if (field.localized) found.push([...c.path, field.name].join("."));
+ *     return undefined;
+ *   },
+ *   combine: () => undefined, // collect-only: nothing to assemble
+ * };
+ * ```
+ *
+ * @see {@link walkFields}
+ * @public
+ */
+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;
+    /** Enter an `array`/`blocks` boundary. Return one {@link ChildCursor} per element, or a signal. */
+    enterList(field: ArrayField | BlocksField, cursor: Cursor): ChildCursor<Cursor>[] | WalkSignal;
+    /**
+     * Visit a data-affecting leaf. `field` is a {@link LeafField} — 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
+     * `undefined` to drop it.
+     */
+    leaf(field: LeafField, 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
+     * the container from its parent (e.g. an empty object after filtering).
+     */
+    combine(container: ContainerInfo, children: ChildOutput<Out>[], cursor: Cursor): Out | undefined;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ *
+ * Shapes this is designed to subsume (one engine, many callers):
+ * - build-tree (filter / reconcile) — reconstruct values in `combine`.
+ * - collect + mutate (field-chunk collector) — push/mutate in `leaf`, `combine` is a no-op.
+ * - navigate + early-exit (path resolver) — `enter*` returns `'skip'`/`'stop'`.
+ *
+ * @template Cursor - The data position threaded through the walk. The engine never reads it;
+ * it only passes it to your callbacks and stores the cursors you return. Constrained to
+ * `object` so a cursor can never collide with a {@link WalkSignal} string (`'skip'`/`'stop'`).
+ * @template Out - What you produce per leaf and assemble per container. Use `void` for a
+ * collect-only walk (accumulate in a closure, return `undefined` from `combine`).
+ *
+ * @example
+ * A collect-only walker that records the path of every localized leaf:
+ * ```ts
+ * type Cursor = { data: Record<string, unknown>; path: string[] };
+ * const found: string[] = [];
+ *
+ * const walker: FieldWalker<Cursor, void> = {
+ *   enterObject: (field, c) =>
+ *     isRecord(c.data[field.name])
+ *       ? { data: c.data[field.name], path: [...c.path, field.name] }
+ *       : "skip",
+ *   enterList: (field, c) => toItemCursors(field, c),
+ *   leaf: (field, c) => {
+ *     if (field.localized) found.push([...c.path, field.name].join("."));
+ *     return undefined;
+ *   },
+ *   combine: () => undefined, // collect-only: nothing to assemble
+ * };
+ * ```
+ *
+ * @see {@link walkFields}
+ * @public
+ */ export { };
+
+//# sourceMappingURL=types.js.map