treege 3.0.0-beta.9 → 3.0.0-beta.91

package/dist/renderer/types/renderer.d.ts

@@ -1,7 +1,8 @@
 import { Node } from '@xyflow/react';
-import { FormEvent, ReactNode } from 'react';
+import { ComponentType, FormEvent, ReactNode } from 'react';
 import { SerializableFile } from '../utils/file';
-import { Flow, InputNodeData, InputType, TreegeNodeData, UINodeData, UIType } from '../../shared/types/node';
+import { FlowStep } from '../utils/step';
+import { Flow, GroupNodeData, HttpHeaders, InputNodeData, InputOption, InputType, TreegeNodeData, UINodeData, UIType } from '../../shared/types/node';
 /**
  * Type mapping for input values based on input type
  */
@@ -18,6 +19,7 @@ export type InputValueTypeMap = {
     password: string;
     radio: string;
     select: string | string[];
+    submit: undefined;
     switch: boolean;
     text: string;
     textarea: string;
@@ -28,48 +30,178 @@ export type InputValueTypeMap = {
  * Form values stored during rendering
  */
 export type FormValues = Record<string, any>;
+export type Meta = {
+    httpResponse?: unknown;
+};
+/**
+ * Extra data injected by the consuming app into every submission, merged at the
+ * top level of the payload — both the object passed to `onSubmit` and the body
+ * of the built-in HTTP submit request. Use it for fields that live in the host
+ * app rather than the form itself (e.g. the logged-in `userId`, a tenant id).
+ *
+ * Either a static object or a function of the current (name-keyed) form values,
+ * evaluated at submit time so the extra data can be derived from the answers or
+ * read fresh (e.g. a rotating auth token). The extra keys are spread last, so
+ * they intentionally override a same-named form field.
+ */
+export type ExtraPayload = Record<string, unknown> | ((values: FormValues) => Record<string, unknown>);
 /**
  * Union of all possible input value types
  */
-export type InputValue = string | number | boolean | string[] | SerializableFile | SerializableFile[] | [string, string] | [string | undefined, string | undefined] | null;
+export type InputValue = string | number | boolean | string[] | SerializableFile | SerializableFile[] | [string, string] | [string | undefined, string | undefined] | null | undefined;
 /**
- * Props for input components with dynamic value typing
- * All form state is provided via props for easier custom component implementation
+ * A field the input's dynamic options depend on that is not yet filled.
  */
-export type InputRenderProps<T extends InputType = InputType> = {
+export type MissingDependency = {
     /**
-     * The node data for this input field
+     * The referenced node id.
      */
-    node: Node<InputNodeData>;
+    id: string;
     /**
-     * Current value of the input field (typed based on input type when T is specified)
+     * The referenced field's translated, end-user-facing label.
+     */
+    label: string;
+};
+/**
+ * HTML-spreadable props for an input control — safe to spread directly onto a
+ * DOM element: `<input {...field} />`. Intentionally excludes `label`,
+ * `helperText`, and `error` (not valid DOM attributes); those live in
+ * `InputExtraProps`.
+ */
+export type InputFieldProps<T extends InputType = InputType> = {
+    /**
+     * Unique field id (nodeId). Use for the element `id`.
+     */
+    id: string;
+    /**
+     * Field name (resolved using priority: name > label > nodeId).
+     */
+    name: string;
+    /**
+     * Current value of the input (typed by input type when T is specified).
      */
     value: InputValueTypeMap[T];
     /**
-     * Function to update the input value
-     * @param value - The new value (typed based on input type when T is specified)
+     * Translated placeholder (already processed with current language).
      */
-    setValue: (value: InputValueTypeMap[T]) => void;
+    placeholder?: string;
     /**
-     * Validation error message for this field (if any)
+     *  Whether the field is required.
      */
-    error?: string;
+    required?: boolean;
+    /**
+     * Set when the field has a validation error.
+     */
+    "aria-invalid"?: boolean;
+};
+/**
+ * Treege-specific props that are NOT DOM attributes: state setters, resolved
+ * translations, validation and runtime metadata. Passed as the second argument
+ * of an input renderer so the first one (`InputFieldProps`) stays spreadable.
+ */
+export type InputExtraProps<T extends InputType = InputType> = {
+    /**
+     * The node data for this input field.
+     */
+    node: Node<InputNodeData>;
     /**
-     * Translated label (already processed with current language)
+     * Function to update the input value.
+     * @param value - The new value (typed by input type when T is specified)
      */
+    setValue: (value: InputValueTypeMap[T]) => void;
+    /**
+     * Validation error message for this field (if any).
+     */
+    error?: string;
+    /** Translated label (already processed with current language). */
     label?: string;
     /**
-     * Translated placeholder (already processed with current language)
+     * Resolved input label component: the consumer's `components.inputLabel` when
+     * provided, otherwise the platform `DefaultInputLabel`. Default inputs render
+     * it as `<InputLabel label={label} required={node.data.required} htmlFor={id} />`;
+     * it renders nothing when no label is configured. Exposed so custom input
+     * renderers can reuse the same (overridable) label.
      */
-    placeholder?: string;
+    InputLabel: InputLabelRenderer;
     /**
-     * Translated helper text (already processed with current language)
+     * Translated helper text (already processed with current language).
      */
     helperText?: string;
+    /**
+     * Fields this input's dynamic options depend on that are not yet filled
+     * (its unresolved `{{nodeId}}` template variables). Empty when none — use it
+     * to hint the user which fields to complete before this input can load.
+     */
+    missingDependencies: MissingDependency[];
+    /**
+     * Missing required fields on form submit (for submit inputs).
+     */
+    missingRequiredFields?: string[];
+    /**
+     * Whether the form is currently being submitted (for submit inputs).
+     */
+    isSubmitting?: boolean;
+    /**
+     * Editor-only extension slot: when provided, option-based renderers (radio,
+     * checkbox) call this for each option to paint inline extras next to it
+     * (e.g. value preview, edit / delete buttons). `variant` is a renderer-side
+     * layout hint (e.g. `"card"` for radio cards). Returning `null` skips the
+     * slot for that option. Left undefined in runtime so the renderers stay
+     * runtime-pure.
+     */
+    renderOptionExtras?: (option: {
+        option: InputOption;
+        index: number;
+        variant?: string;
+    }) => ReactNode;
+    /**
+     * Editor-only layout flag. When `true`, option-based renderers force their
+     * option labels to a single truncated line (block + max-w-full + truncate)
+     * and reserve room on the right for the `renderOptionExtras` overlay.
+     * Defaults to `false` (multi-line, runtime-pure).
+     */
+    compactOptions?: boolean;
+};
+/**
+ * Props passed to an input renderer: the spreadable `field` props (DOM-safe, so
+ * `field` can be spread onto a control — `<input {...field} />`) and the Treege
+ * `extra` props (state setters, translations, metadata).
+ */
+export type InputRenderProps<T extends InputType = InputType> = {
+    field: InputFieldProps<T>;
+    extra: InputExtraProps<T>;
 };
+/**
+ * An input renderer — a React component, so it can use hooks and is rendered
+ * directly (`<Renderer field={field} extra={extra} />`) without a wrapper.
+ */
+export type InputRenderer<T extends InputType = InputType> = ComponentType<InputRenderProps<T>>;
 export type UiRenderProps = {
     node: Node<UINodeData>;
 };
+/**
+ * Props for the input label component shared by all default input renderers.
+ * `label` + `required` are platform-agnostic; the remaining fields are
+ * passthrough hints for the platform (web: `htmlFor`/`id`/`className`,
+ * native: `style`). Implementations should render nothing when `label` is empty
+ * so the technical node key never leaks into the form.
+ */
+export type InputLabelRenderProps = {
+    /** End-user-facing label. Render nothing when empty. */
+    label?: string;
+    /** Whether to render the required marker. */
+    required?: boolean;
+    /** Web: associates the label with the control. */
+    htmlFor?: string;
+    /** Web: id used for `aria-labelledby` on option groups. */
+    id?: string;
+    /** Web: extra class names. */
+    className?: string;
+    /** Native: extra style (typed loosely to avoid a react-native dependency here). */
+    style?: unknown;
+};
+/** Input label component (custom `components.inputLabel` or the platform default). */
+export type InputLabelRenderer = ComponentType<InputLabelRenderProps>;
 /**
  * Props for UI/Group components (use useTreegeContext for state)
  */
@@ -81,7 +213,69 @@ export type NodeRenderProps = {
  * Each input type gets its own properly typed InputRenderProps
  */
 export type InputRenderers = {
-    [K in InputType]?: (props: InputRenderProps<K>) => ReactNode;
+    [K in InputType]?: InputRenderer<K>;
+};
+/**
+ * Props passed to a step renderer. Steps are derived at runtime from the flow's
+ * groups: each contiguous slice of visible nodes sharing the same `parentId`
+ * (or no parent — orphan steps) becomes one step.
+ */
+export type StepRenderProps = {
+    /** The step being rendered (its group id and ordered child nodes). */
+    step: FlowStep;
+    /** Hidden group node carrying the step's metadata (label) — undefined for orphan steps. */
+    groupNode?: Node<GroupNodeData>;
+    /** Zero-based index of this step in the current step sequence. */
+    stepIndex: number;
+    /** Total number of steps currently visible. Recomputes when branching changes. */
+    totalSteps: number;
+    /** True when this is the first step (Back should be hidden/disabled). */
+    isFirstStep: boolean;
+    /**
+     * Whether a Back button should be shown. True on any step past the first, and
+     * also on the first step when the consumer passes an `onBack` prop (to bridge
+     * back-navigation to an outer flow, e.g. a parent modal's steps). Prefer this
+     * over `isFirstStep` to decide whether to render the Back control.
+     */
+    canGoBack: boolean;
+    /**
+     * True when this is the last visible step. The renderer turns Continue
+     * into a submit action on the last step.
+     */
+    isLastStep: boolean;
+    /** Whether all required visible inputs of the step are filled. */
+    canContinue: boolean;
+    /**
+     * True when the step contains an explicit `submit` input node. Such a node is
+     * declarative — it renders no button itself; the step renders the single
+     * submit button (reusing the node's label). Exposed for custom step
+     * implementations that need to know a submit node is present.
+     */
+    hasSubmitInput?: boolean;
+    /**
+     * Translated labels of the current step's required fields still empty. Lines
+     * up with `canContinue`, so the action button can show a tooltip explaining
+     * why Continue/Submit is disabled — on every step, not just the last.
+     */
+    missingFields?: string[];
+    /** Submission in progress (passed through from `useTreegeRenderer`). */
+    isSubmitting?: boolean;
+    /**
+     * Go back: advances to the previous step, or — on the first step, when the
+     * consumer passed an `onBack` prop — invokes that callback instead. No-op on
+     * the first step when no `onBack` prop was provided.
+     */
+    onBack: () => void;
+    /**
+     * Advance to the next step (or trigger submit on the last step). The wrapper
+     * passes `isLastStep` so the implementation can decide between an in-flow
+     * advance and a form submit.
+     */
+    onContinue: () => void;
+    /** Translated label of the group, or empty string for orphan steps. */
+    label?: string;
+    /** The rendered child nodes belonging to this step. */
+    children: ReactNode;
 };
 /**
  * Custom renderer components
@@ -97,21 +291,42 @@ export type TreegeRendererComponents = {
      */
     ui?: Partial<Record<UIType, (props: NodeRenderProps) => ReactNode>>;
     /**
-     * Custom group container renderer
+     * Custom input label, shared by every default input renderer. Receives
+     * `{ label, required, ...platformProps }` and should render nothing when
+     * `label` is empty. Defaults to `DefaultInputLabel` (web/native).
+     */
+    inputLabel?: InputLabelRenderer;
+    /**
+     * Custom step renderer — wraps the current step's nodes and renders the
+     * Back/Continue navigation. Defaults are provided by `DefaultStep` (web/native).
      */
-    group?: (props: NodeRenderProps) => ReactNode;
+    step?: (props: StepRenderProps) => ReactNode;
     /**
-     * Custom form wrapper
+     * Custom form wrapper. `id` (when provided via the `formId` prop) should be
+     * forwarded to the underlying `<form>` element to keep external submit
+     * buttons working.
      */
     form?: (props: {
         children: ReactNode;
-        onSubmit: (e: FormEvent) => void;
+        id?: string;
+        onSubmit: (e: FormEvent<HTMLFormElement>) => void;
     }) => ReactNode;
     /**
-     * Custom submit button (pure button without wrapper)
+     * Custom submit button (supports both web and native variants)
+     * Web variant: { label?: string; disabled?: boolean; isSubmitting?: boolean; ...otherHTMLAttributes }
+     * Native variant: { children?: ReactNode; disabled?: boolean; isSubmitting?: boolean; onPress?: () => void }
      */
     submitButton?: (props: {
         label?: string;
+        disabled?: boolean;
+        isSubmitting?: boolean;
+        [key: string]: unknown;
+    } | {
+        children?: ReactNode;
+        disabled?: boolean;
+        isSubmitting?: boolean;
+        onPress?: () => void;
+        [key: string]: unknown;
     }) => ReactNode;
     /**
      * Custom submit button wrapper (e.g., for tooltip with missing fields)
@@ -120,9 +335,14 @@ export type TreegeRendererComponents = {
         children: ReactNode;
         missingFields?: string[];
     }) => ReactNode;
+    /**
+     * Custom loading skeleton, rendered in place of the form while the
+     * `isLoading` prop is true. Defaults to `DefaultLoadingSkeleton` (web).
+     */
+    loadingSkeleton?: () => ReactNode;
 };
 /**
- * Configuration options that can be set globally via TreegeConfigProvider
+ * Configuration options that can be set globally via TreegeRendererProvider
  * or locally via TreegeRenderer config prop
  */
 export type TreegeRendererConfig = {
@@ -130,6 +350,15 @@ export type TreegeRendererConfig = {
      * Custom component renderers
      */
     components?: TreegeRendererComponents;
+    /**
+     * Global HTTP headers applied to every request issued by the renderer
+     * (HTTP inputs, submit buttons). Field-level headers with the same key
+     * (case-insensitive) take precedence over these.
+     *
+     * @example
+     * headers={{ Authorization: `Bearer ${accessToken}` }}
+     */
+    headers?: HttpHeaders;
     /**
      * Google Maps API key for address autocomplete
      * If not provided, falls back to free Nominatim (OpenStreetMap)
@@ -150,53 +379,107 @@ export type TreegeRendererConfig = {
      * @default "onSubmit"
      */
     validationMode?: "onChange" | "onSubmit";
+    /**
+     * Whether to display the "Powered by Treege" credit at the bottom of the form.
+     * @default true
+     */
+    showPoweredBy?: boolean;
+    /**
+     * Base URL prepended to every **relative** HTTP url issued by the renderer
+     * (HTTP inputs, dynamic options, and submit). Use this to keep the tree
+     * JSON environment-agnostic — store relative paths in the tree and supply
+     * the host here per environment:
+     *
+     * @example
+     * // In the tree: "url": "/v2/entities/{{nodeId}}/sub-entities"
+     * <TreegeRenderer flow={tree} baseUrl={import.meta.env.VITE_API_URL} />
+     *
+     * Absolute urls (starting with `http://` or `https://`) are left untouched,
+     * so a field can still point at an external API. Template variables are
+     * resolved first, then the base URL is applied to the result.
+     */
+    baseUrl?: string;
 };
 /**
  * Props for the TreegeRenderer component
+ *
+ * Inherits all configuration fields from TreegeRendererConfig (components,
+ * headers, googleApiKey, language, theme, validationMode) and adds the
+ * instance-specific ones (flow, callbacks, initial values, etc.).
  */
-export type TreegeRendererProps = {
+export interface TreegeRendererProps extends TreegeRendererConfig {
     /**
-     * Custom component renderers
+     * Additional class name for the renderer container
      */
-    components?: TreegeRendererComponents;
+    className?: string;
     /**
-     * Flow or array of flows
-     * - If a single Flow: renders that flow
-     * - If an array: first flow is the main flow, others are sub-flows available for FlowNodes
+     * Extra data injected into every submission, merged at the top level of both
+     * the `onSubmit` payload and the built-in HTTP submit body. Use it for values
+     * owned by the host app rather than the form (e.g. the logged-in `userId`).
+     * See {@link ExtraPayload}.
+     *
+     * @example
+     * <TreegeRenderer flow={tree} extraPayload={{ userId }} />
+     * @example
+     * <TreegeRenderer flow={tree} extraPayload={() => ({ token: getToken() })} />
      */
-    flows?: Flow | Flow[] | null;
+    extraPayload?: ExtraPayload;
     /**
-     * Google Maps API key for address autocomplete
-     * If not provided, falls back to free Nominatim (OpenStreetMap)
+     * Flow to render. `null` / `undefined` renders nothing.
      */
-    googleApiKey?: string;
+    flow?: Flow | null;
     /**
-     * Initial form values
+     * Sets the `id` attribute on the underlying `<form>` element, so a submit
+     * button rendered outside the renderer can target it via the native HTML
+     * `form` attribute: `<button type="submit" form={formId}>`. Web only.
+     */
+    formId?: string;
+    /**
+     * Initial form values — use this to pre-fill the form when editing a record
+     * that was already submitted.
+     *
+     * Keys can be either `node.id` OR the same name-based keys you receive back in
+     * `onChange` / `onSubmit`, so the previously-submitted object can be fed
+     * straight back in without any remapping.
+     *
+     * Reactive: if this changes after mount (e.g. an async-fetched record resolves
+     * later), the form is re-seeded automatically. A new object literal of
+     * identical content does NOT reset the form, so in-progress user edits are
+     * preserved.
      */
     initialValues?: FormValues;
     /**
-     * Current language for translations
+     * When true, renders a loading skeleton instead of the form. Useful while
+     * the flow is being fetched. Customizable via `components.loadingSkeleton`.
      */
-    language?: string;
+    isLoading?: boolean;
+    /**
+     * When true, forces the submit/continue button into its loading state
+     * (spinner + disabled). Use this to keep the button busy while an async
+     * `onSubmit` is still resolving on the consumer side. It is OR-ed with the
+     * renderer's own internal submitting state, so it only ever adds to it.
+     */
+    isSubmitting?: boolean;
+    /**
+     * Called when the user clicks Back on the FIRST step. Provide this to bridge
+     * back-navigation to an outer flow (e.g. a parent modal's steps): when set, a
+     * Back button is shown on the first step and triggers this callback instead
+     * of being a no-op. Has no effect on later steps, which always navigate back
+     * internally.
+     */
+    onBack?: () => void;
     /**
      * Callback when form values change
      */
     onChange?: (values: FormValues) => void;
     /**
      * Callback when form is submitted
+     * @param values - Form values (keyed by field name or node ID)
+     * @param meta - Optional metadata about the submission (e.g., HTTP response data)
      */
-    onSubmit?: (values: FormValues) => void;
-    /**
-     * Theme for the renderer
-     * @default "dark"
-     */
-    theme?: "dark" | "light";
+    onSubmit?: (values: FormValues, meta?: Meta) => void;
     /**
      * Custom validation function
      */
     validate?: (values: FormValues, nodes: Node<TreegeNodeData>[]) => Record<string, string>;
-    /**
-     * Validation mode
-     */
-    validationMode?: "onChange" | "onSubmit";
-};
+}

package/dist/renderer/utils/extraPayload.d.ts

@@ -0,0 +1,21 @@
+import { ExtraPayload, FormValues } from '../types/renderer';
+/**
+ * Merge the consumer-provided `extraPayload` onto a base submission payload.
+ * This is the single chokepoint behind the `extraPayload` prop, used both for
+ * the `onSubmit` callback payload and the built-in HTTP submit body.
+ *
+ * `extraPayload` may be a static object or a function of the current
+ * (name-keyed) values — the function form lets the extra data be read at submit
+ * time (e.g. a freshly-read auth token). The extra fields are spread **last**,
+ * so a consumer-injected key (e.g. `userId`) intentionally wins over a
+ * same-named form field.
+ *
+ * Edge cases:
+ * - No `extraPayload`, or it resolves to a non-object (array / primitive) →
+ *   the base is returned untouched (nothing to merge).
+ * - Base is `undefined`/`null` (e.g. a submit config that would otherwise send
+ *   no body) → the extra is sent on its own, so the injected data still goes out.
+ * - Base is a non-object → returned untouched, since there is no top level to
+ *   merge into.
+ */
+export declare const mergeExtraPayload: <T>(base: T, extraPayload: ExtraPayload | undefined, values: FormValues) => T | Record<string, unknown>;

package/dist/renderer/utils/file.d.ts

@@ -1,13 +1,5 @@
-/**
- * Represents a serializable file object with base64 data
- */
-export interface SerializableFile {
-    name: string;
-    size: number;
-    type: string;
-    lastModified: number;
-    data: string;
-}
+import { SerializableFile } from '../../shared/types/file';
+export type { SerializableFile };
 /**
  * Converts a File object to a serializable format with base64 data
  */
@@ -20,3 +12,25 @@ export declare const serializableToFile: (serializable: SerializableFile) => Fil
  * Converts multiple File objects to serializable format
  */
 export declare const filesToSerializable: (files: File[]) => Promise<SerializableFile[]>;
+/**
+ * Derive a readable file name from a URL's last path segment (query/hash stripped).
+ */
+export declare const fileNameFromUrl: (url: string) => string;
+/**
+ * Whether a file's `data` is a URL to fetch/link to (an http(s) or relative
+ * path) rather than inline base64/blob content. Useful to decide whether to
+ * render the file as a clickable link or resolve it against a base URL.
+ */
+export declare const isRemoteFileData: (data: string | null | undefined) => boolean;
+/**
+ * Normalizes a file field value into an array of `SerializableFile`.
+ * Handles a single file, an array, and empty (`null`/`undefined`) values. A
+ * stored document may also be referenced by a bare URL string (or an array
+ * containing some) — those are coerced into a `SerializableFile` whose `data`
+ * holds the URL and whose `name` is derived from it.
+ */
+export declare const normalizeSerializableFiles: (value: SerializableFile | string | Array<SerializableFile | string> | null | undefined) => SerializableFile[];
+/**
+ * Formats a byte size into a human-readable string (B / KB / MB)
+ */
+export declare const formatFileSize: (size: number) => string;

package/dist/renderer/utils/flow.d.ts

@@ -1,7 +1,7 @@
 import { Edge, Node } from '@xyflow/react';
 import { FormValues } from '../types/renderer';
 import { ConditionalEdgeData } from '../../shared/types/edge';
-import { Flow, TreegeNodeData } from '../../shared/types/node';
+import { TreegeNodeData } from '../../shared/types/node';
 /**
  * Result from computing the flow render state
  * Contains everything needed to render the form and determine its state
@@ -72,20 +72,3 @@ export declare const findStartNode: (nodes: Node<TreegeNodeData>[], edges: Edge[
  * @returns Complete flow render state (visible nodes, end-of-path flag, etc.)
  */
 export declare const getFlowRenderState: (nodes: Node<TreegeNodeData>[], edges: Edge<ConditionalEdgeData>[], formValues: FormValues) => FlowRenderState;
-/**
- * Merge multiple flows into a single flow by recursively replacing FlowNodes with their target flow's nodes
- *
- * This function takes a flow or an array of flows, automatically detects the main flow, then:
- * 1. Replaces each FlowNode with the nodes from its target flow
- * 2. Preserves the order of nodes by inserting sub-flow nodes at the FlowNode position
- * 3. Redirects edges that point to FlowNodes to the first node of the target flow
- * 4. Connects the last nodes of sub-flows to the nodes that followed the FlowNode
- *
- * Main flow detection:
- * - The main flow is automatically identified as the one that references other flows but is not referenced itself
- * - This allows flows to be passed in any order without breaking the merge logic
- *
- * @param flows - A single Flow or an array of flows (can be null/undefined)
- * @returns A single merged Flow containing all nodes and edges
- */
-export declare const mergeFlows: (flows?: Flow | Flow[] | null) => Flow;

package/dist/renderer/utils/form.d.ts

@@ -17,10 +17,62 @@ export declare const isFieldEmpty: (value: unknown) => boolean;
  * @returns True if the field has been filled (any value except undefined/null), false otherwise
  */
 export declare const checkFormFieldHasValue: (fieldName: string | undefined, formValues: FormValues) => boolean;
+/**
+ * Resolve the default value for a single input node given the current form
+ * values. Mirrors the seeding rules used at mount:
+ * - `static`: returns the configured `staticValue`
+ * - `reference`: returns the (raw, untransformed) value of the referenced field
+ *   if that field currently has a value
+ *
+ * Returns `undefined` when the node has no applicable default. The raw
+ * reference value is intentionally returned untransformed — transformations are
+ * handled separately by `calculateReferenceFieldUpdates`.
+ *
+ * @param node - The input node
+ * @param values - Current form values (keyed by node id)
+ * @returns The default value to apply, or `undefined`
+ */
+export declare const resolveNodeDefaultValue: (node: Node<InputNodeData>, values: FormValues) => unknown;
+/**
+ * Build the initial (nodeId-keyed) form state from consumer-provided values.
+ *
+ * Consumers can pass `initialValues` keyed either by `node.id` OR by the same
+ * key shape they receive back in `onChange`/`onSubmit` (resolved via
+ * `resolveNodeKey`: name > label > node.id). This lets an edit screen feed the
+ * previously-submitted object straight back in without any remapping.
+ *
+ * After normalizing provided values, node `defaultValue`s (static / reference)
+ * are applied to any field still left unset — matching a fresh mount.
+ *
+ * @param initialValues - Values provided by the consumer (id- or name-keyed)
+ * @param inputNodes - All input nodes of the flow
+ * @returns Form values keyed strictly by node id
+ */
+export declare const buildInitialFormValues: (initialValues: FormValues, inputNodes: Node<InputNodeData>[]) => FormValues;
 /**
  * Convert internal form values (keyed by nodeId) to external format (keyed by name)
  * When multiple nodes share the same name, later values overwrite earlier ones
- * example: convertFormValuesToNamedFormat({ id1: 'Alice', id2: 'Bob' }, [ { id: 'id1', data: { name: 'firstName' } }, { id: 'id2', data: { name: 'lastName' } } ])
- * returns { firstName: 'Alice', lastName: 'Bob' }
+ * Priority for key naming: name > label (en) > nodeId
+ * example: convertFormValuesToNamedFormat({ id1: 'Alice', id2: 'Bob' }, [ { id: 'id1', data: { name: 'firstName' } }, { id: 'id2', data: { label: { en: 'Last Name' } } } ])
+ * returns { firstName: 'Alice', 'Last Name': 'Bob' }
  */
 export declare const convertFormValuesToNamedFormat: (formValues: FormValues, nodes: Node<InputNodeData>[]) => Record<string, unknown>;
+/**
+ * Apply transformation to a reference field value
+ * @param value - The source value to transform
+ * @param transformFunction - The transformation function to apply
+ * @param objectMapping - Optional mapping for toObject transformation
+ * @returns The transformed value
+ */
+export declare const applyReferenceTransformation: (value: unknown, transformFunction: "toString" | "toNumber" | "toBoolean" | "toArray" | "toObject" | null | undefined, objectMapping?: Array<{
+    sourceKey: string;
+    targetKey: string;
+}>) => unknown;
+/**
+ * Calculate updated values for fields with reference defaults
+ * @param inputNodes - Array of input nodes
+ * @param formValues - Current form values
+ * @param prevFormValues - Previous form values (for change detection)
+ * @returns Object containing fields that need to be updated
+ */
+export declare const calculateReferenceFieldUpdates: (inputNodes: Node<InputNodeData>[], formValues: FormValues, prevFormValues: FormValues) => FormValues;