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

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

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

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

@@ -0,0 +1,51 @@
+import type { Field } from "payload";
+import type { 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
+ * (filtering, reconciling, collecting, navigating).
+ *
+ * The engine owns structural dispatch (via {@link classifyField} / {@link tabScopes}) and the
+ * recursion; the caller owns the **data** through the opaque `Cursor` and decides what to
+ * produce. The engine never reads the cursor — so the caller can thread one, two, or more
+ * parallel data trees (plus a path) inside it. Containers are assembled bottom-up via
+ * `combine`, after their children.
+ *
+ * @template Cursor - The caller's data position threaded through the walk (e.g. the current
+ * data object, a `{ source, target }` pair, plus a path). Constrained to `object` so a cursor
+ * can never collide with a {@link WalkSignal} string (`'skip'`/`'stop'`).
+ * @template Out - What the walker produces per node and assembles per container (e.g. a
+ * rebuilt data subtree, or `void` for a collect-only walk).
+ *
+ * @param fields - The schema to walk (a collection/global/group `fields` array).
+ * @param root - The initial `Cursor` paired with the top-level `fields`.
+ * @param walker - The behavior to drive: `enterObject` / `enterList` derive child cursors (or
+ * return a {@link WalkSignal} to `'skip'` a branch or `'stop'` the whole walk), `leaf`
+ * produces a value per data-affecting leaf, and `combine` assembles each container from its
+ * children.
+ * @returns The root `combine` output. `undefined` if the walk was halted by `'stop'` before the
+ * root assembled, OR if the root `combine` itself returned `undefined` (e.g. a collect-only
+ * walker). To distinguish "stopped" from "empty result", track it via the cursor, not this value.
+ *
+ * @example
+ * Keep only localized leaves and rebuild the data tree (a "filter" walk):
+ * ```ts
+ * type Cursor = { data: Record<string, unknown> };
+ *
+ * const filtered = walkFields<Cursor, unknown>(schema, { data }, {
+ *   enterObject: (field, c) =>
+ *     isRecord(c.data[field.name]) ? { data: c.data[field.name] } : "skip",
+ *   enterList: (field, c) => toItemCursors(field, c), // one ChildCursor per element
+ *   leaf: (field, c) => (field.localized ? c.data[field.name] : undefined),
+ *   combine: (container, children) => {
+ *     if (children.length === 0) return undefined; // drop empty containers
+ *     if (container.kind === "list") return children.map((ch) => ch.out);
+ *     return Object.fromEntries(children.map((ch) => [ch.key, ch.out]));
+ *   },
+ * });
+ * ```
+ *
+ * @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;