treege 3.0.0-beta.6 → 3.0.0-beta.61

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

@@ -1,7 +1,8 @@
 import { Node } from '@xyflow/react';
 import { 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,30 +30,124 @@ export type InputValueTypeMap = {
  * Form values stored during rendering
  */
 export type FormValues = Record<string, any>;
+export type Meta = {
+    httpResponse?: 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> = {
-    node: Node<InputNodeData>;
+export type MissingDependency = {
+    /**
+     * The referenced node id.
+     */
+    id: string;
+    /**
+     * 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> = {
     /**
-     * Current value of the input field (typed based on input type when T is specified)
+     * 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).
+     */
+    placeholder?: string;
+    /**
+     *  Whether the field is required.
+     */
+    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>;
+    /**
+     * 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)
+     * Validation error message for this field (if any).
      */
     error?: string;
+    /** Translated label (already processed with current language). */
+    label?: string;
+    /**
+     * 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;
 };
+/**
+ * An input renderer. Receives the spreadable `field` props (DOM-safe) and the
+ * Treege `extra` props (state setters, translations, metadata) as two separate
+ * arguments, so `field` can be spread onto a control: `<input {...field} />`.
+ */
+export type InputRenderer<T extends InputType = InputType> = (field: InputFieldProps<T>, extra: InputExtraProps<T>) => ReactNode;
 export type UiRenderProps = {
     node: Node<UINodeData>;
 };
@@ -66,7 +162,50 @@ 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;
+    /**
+     * 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;
+    /**
+     * Translated labels of required fields still empty. Only populated on the
+     * last step so the step can show a tooltip explaining why submit is disabled.
+     */
+    missingFields?: string[];
+    /** Submission in progress (passed through from `useTreegeRenderer`). */
+    isSubmitting?: boolean;
+    /** Advance to the previous step. No-op on the first step. */
+    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
@@ -82,21 +221,32 @@ export type TreegeRendererComponents = {
      */
     ui?: Partial<Record<UIType, (props: NodeRenderProps) => ReactNode>>;
     /**
-     * Custom group container renderer
+     * 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
      */
     form?: (props: {
         children: ReactNode;
-        onSubmit: (e: FormEvent) => void;
+        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; ...otherHTMLAttributes }
+     * Native variant: { children?: ReactNode; disabled?: boolean; isSubmitting?: boolean; onPress?: () => void }
      */
     submitButton?: (props: {
         label?: string;
+        disabled?: 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)
@@ -105,9 +255,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 = {
@@ -115,6 +270,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)
@@ -135,53 +299,59 @@ export type TreegeRendererConfig = {
      * @default "onSubmit"
      */
     validationMode?: "onChange" | "onSubmit";
+    /**
+     * 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
+     * Flow to render. `null` / `undefined` renders nothing.
      */
-    flows?: Flow | Flow[] | null;
-    /**
-     * Google Maps API key for address autocomplete
-     * If not provided, falls back to free Nominatim (OpenStreetMap)
-     */
-    googleApiKey?: string;
+    flow?: Flow | null;
     /**
      * Initial form values
      */
     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;
     /**
      * 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/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

@@ -20,7 +20,27 @@ export declare const checkFormFieldHasValue: (fieldName: string | undefined, for
 /**
  * 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;

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

@@ -0,0 +1,161 @@
+import { FormValues } from '../types/renderer';
+import { HttpHeaders, InputOption, OptionsSourceMapping, QueryParams } from '../../shared/types/node';
+/**
+ * Merge multiple lists of HTTP headers. Later sources override earlier ones
+ * when they specify the same key (case-insensitive comparison, since HTTP
+ * header names are case-insensitive). The casing of the latest occurrence
+ * is preserved in the output.
+ */
+export declare const mergeHttpHeaders: (...sources: (HttpHeaders | undefined)[]) => HttpHeaders;
+/**
+ * Resolve `{{templateVar}}` placeholders in every value of a header/query-param
+ * record, leaving the keys untouched. Returns `undefined` for `undefined` so
+ * callers can pass the result straight into `mergeHttpHeaders`/`makeHttpRequest`.
+ */
+export declare const resolveTemplateRecord: (record: Record<string, string> | undefined, values: FormValues, options?: {
+    encode?: boolean;
+    json?: boolean;
+}) => Record<string, string> | undefined;
+/**
+ * Append query parameters to a URL. Entries with an empty key are skipped,
+ * keys and values are URL-encoded, and `?` or `&` is chosen automatically
+ * based on whether the URL already has a query string. Values are expected
+ * to already have their template variables resolved.
+ */
+export declare const appendQueryParams: (url: string, params?: QueryParams) => string;
+/**
+ * Prepend a base URL to a relative URL. Absolute urls (starting with
+ * `http://` or `https://`, case-insensitive) and protocol-relative urls
+ * (`//host/...`) are returned untouched, so individual fields can still
+ * target an external API. A single slash is enforced at the join so a
+ * trailing slash on the base and/or a leading slash on the path don't
+ * produce `//`. When no base URL is configured, the url is returned as-is.
+ *
+ * Expects the url to already have its template variables resolved.
+ */
+export declare const resolveUrl: (url: string, baseUrl?: string) => string;
+/**
+ * Result of an HTTP request
+ */
+export interface HttpRequestResult {
+    /**
+     * Whether the request was successful (2xx status code)
+     */
+    success: boolean;
+    /**
+     * Response data (parsed JSON or raw text)
+     */
+    data?: unknown;
+    /**
+     * Error message if request failed
+     */
+    error?: string;
+    /**
+     * HTTP status code
+     */
+    status?: number;
+    /**
+     * HTTP status text
+     */
+    statusText?: string;
+}
+/**
+ * Options for making an HTTP request
+ */
+export interface HttpRequestOptions {
+    /**
+     * The URL to call (should already have variables replaced)
+     */
+    url: string;
+    /**
+     * HTTP method
+     */
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /**
+     * Request headers
+     */
+    headers?: HttpHeaders;
+    /**
+     * Query parameters appended to the URL (values should already have their
+     * template variables resolved; keys/values are URL-encoded here)
+     */
+    queryParams?: QueryParams;
+    /**
+     * Request body (for POST/PUT/PATCH)
+     */
+    body?: string;
+    /**
+     * Optional abort signal to cancel the request
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Make an HTTP request with common error handling and response parsing
+ *
+ * This is a shared utility used by both HTTP inputs and submit buttons
+ * to ensure consistent behavior across the library.
+ *
+ * @param options - Request options
+ * @returns Promise with request result
+ */
+export declare const makeHttpRequest: (options: HttpRequestOptions) => Promise<HttpRequestResult>;
+/**
+ * Replace template variables in a string with actual values from form data
+ *
+ * Uses {{fieldId}} syntax for all replacements (URLs, JSON bodies, etc.)
+ *
+ * Smart JSON handling:
+ * - Strings: automatically wrapped in quotes and escaped
+ * - Numbers/Booleans: converted to JSON-safe format
+ * - Arrays/Objects: JSON.stringify
+ *
+ * @param template - The template string containing variables
+ * @param values - Form values to substitute
+ * @param options - Replacement options
+ * @param options.encode - Whether to URL-encode the replaced values (for URLs)
+ * @param options.json - Whether to use smart JSON handling (for request bodies)
+ * @returns The string with variables replaced
+ *
+ * @example
+ * // For URLs (with encoding)
+ * replaceTemplateVariables("https://api.com/users/{{userId}}", { userId: "john doe" }, { encode: true })
+ * // => "https://api.com/users/john%20doe"
+ *
+ * // For JSON bodies (smart handling)
+ * replaceTemplateVariables('{"name": {{userName}}}', { userName: "John" }, { json: true })
+ * // => '{"name": "John"}'
+ *
+ * replaceTemplateVariables('{"age": {{userAge}}}', { userAge: 25 }, { json: true })
+ * // => '{"age": 25}'
+ */
+export declare const replaceTemplateVariables: (template: string | undefined, values: FormValues, options?: {
+    encode?: boolean;
+    json?: boolean;
+}) => string;
+/**
+ * Replace template variables in response data (for redirect URLs)
+ *
+ * Supports {{response.field}} format to access response data
+ *
+ * @param template - The template string containing variables
+ * @param responseData - Response data object
+ * @returns The string with variables replaced
+ */
+export declare const replaceResponseVariables: (template: string | undefined, responseData: unknown) => string;
+/**
+ * Extract a value from an object using a path that supports dot notation
+ * and array indexing. Examples:
+ * - "data.users" → obj.data.users
+ * - "results[0].name" → obj.results[0].name
+ *
+ * @param obj - The object to extract value from
+ * @param path - The path expression (empty string returns the object as-is)
+ * @returns The value at the path, or undefined if not found
+ */
+export declare const getValueByPath: (obj: unknown, path: string) => unknown;
+/**
+ * Project a list-shaped HTTP response into InputOption objects, applying
+ * a field-to-property mapping. Returns an empty array when the data is not
+ * iterable or required fields are missing.
+ */
+export declare const extractOptionsFromResponse: (response: unknown, responsePath: string | undefined, mapping: OptionsSourceMapping) => InputOption[];

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

@@ -6,9 +6,37 @@ import { InputNodeData, TreegeNodeData } from '../../shared/types/node';
  * @returns Array of input nodes only
  */
 export declare const getInputNodes: (nodes: Node<TreegeNodeData>[]) => Node<InputNodeData>[];
+/**
+ * Resolve the key name for an input node using priority: name > label (en) > nodeId
+ * This is the single source of truth for key resolution across the application
+ * @param node - The input node
+ * @returns The resolved key (name, label, or node ID)
+ */
+export declare const resolveNodeKey: (node: Node<InputNodeData>) => string;
+/**
+ * Resolve a human, end-user-facing label for an input node, preferring the
+ * translated `label` for the given language over the technical `name`. Used
+ * when surfacing field references to users (e.g. dependency hints). Priority:
+ * translated label > name > node id. This differs from `resolveNodeKey`, which
+ * prioritizes `name` for form-submission keys.
+ * @param node - The input node
+ * @param language - The current language code
+ * @returns The resolved display label
+ */
+export declare const resolveNodeLabel: (node: Node<InputNodeData>, language: string) => string;
+/**
+ * Resolve the placeholder text for an input, falling back to the static
+ * "newAnswer" translation for textfield-like types when the user has not
+ * defined a placeholder for the current language.
+ * @param data - The input node data
+ * @param language - The current language code
+ * @returns The resolved placeholder string (empty string if none available)
+ */
+export declare const resolveInputPlaceholder: (data: InputNodeData, language: string) => string;
 /**
  * Get the field name (DOM name attribute) for a given node ID
- * Uses node.data.name if available, otherwise falls back to nodeId
+ * Priority: name > label (en) > nodeId
+ * This must match the logic in convertFormValuesToNamedFormat for consistency
  * @param nodeId - The ID of the input node
  * @param nodes - Array of input nodes
  * @returns The field name to use in the DOM, or undefined if node not found