treege 3.0.0-beta.5 → 3.0.0-beta.51

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, HttpHeader, 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,20 +30,35 @@ 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
  */
 export type InputRenderProps<T extends InputType = InputType> = {
+    /**
+     * The node data for this input field
+     */
     node: Node<InputNodeData>;
     /**
      * Current value of the input field (typed based on input type when T is specified)
      */
     value: InputValueTypeMap[T];
+    /**
+     * Unique field ID (nodeId)
+     */
+    id: string;
+    /**
+     * Field name (resolved using priority: name > label > nodeId)
+     * Use this for the name and id attributes of the input element
+     */
+    name: string;
     /**
      * Function to update the input value
      * @param value - The new value (typed based on input type when T is specified)
@@ -51,6 +68,46 @@ export type InputRenderProps<T extends InputType = InputType> = {
      * 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)
+     */
+    placeholder?: string;
+    /**
+     * Translated helper text (already processed with current language)
+     */
+    helperText?: string;
+    /**
+     * 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;
 };
 export type UiRenderProps = {
     node: Node<UINodeData>;
@@ -68,6 +125,44 @@ export type NodeRenderProps = {
 export type InputRenderers = {
     [K in InputType]?: (props: InputRenderProps<K>) => ReactNode;
 };
+/**
+ * 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;
+    /** 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 +177,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)
@@ -115,6 +221,12 @@ 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.
+     */
+    headers?: HttpHeader[];
     /**
      * Google Maps API key for address autocomplete
      * If not provided, falls back to free Nominatim (OpenStreetMap)
@@ -138,50 +250,36 @@ export type TreegeRendererConfig = {
 };
 /**
  * Props for the TreegeRenderer component
+ *
+ * Inherits all configuration fields from TreegeRendererConfig (components,
+ * headers, googleApiKey, language, theme, validationMode) and adds the
+ * instance-specific ones (flows, 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;
+    flows?: Flow | null;
     /**
      * Initial form values
      */
     initialValues?: FormValues;
-    /**
-     * Current language for translations
-     */
-    language?: string;
     /**
      * 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,129 @@
+import { FormValues } from '../types/renderer';
+import { HttpHeader, InputOption, OptionsSourceMapping } 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: (HttpHeader[] | undefined)[]) => HttpHeader[];
+/**
+ * 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?: HttpHeader[];
+    /**
+     * 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,26 @@ 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 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

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

@@ -0,0 +1,85 @@
+/**
+ * Configuration for DOMPurify sanitization
+ */
+interface SanitizeOptions {
+    /**
+     * Allow only plain text (strip all HTML tags)
+     * @default true
+     */
+    plainTextOnly?: boolean;
+    /**
+     * Custom allowed tags (when plainTextOnly is false)
+     */
+    allowedTags?: string[];
+    /**
+     * Custom allowed attributes (when plainTextOnly is false)
+     */
+    allowedAttributes?: string[];
+}
+/**
+ * Sanitizes user input to prevent XSS attacks
+ *
+ * This utility wraps DOMPurify and provides secure defaults for the treege library.
+ * It should be used on all user-provided content before rendering, especially:
+ * - Labels from node data
+ * - Helper text
+ * - Placeholder text
+ * - Any content from HTTP responses
+ *
+ * @param input - The string to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized string safe for rendering
+ *
+ * @example
+ * // Plain text only (default behavior)
+ * sanitize('<script>alert("xss")</script>Hello')
+ * // => 'Hello'
+ *
+ * @example
+ * // Allow safe HTML tags
+ * sanitize('<b>Bold text</b><script>alert("xss")</script>', { plainTextOnly: false })
+ * // => '<b>Bold text</b>'
+ *
+ * @example
+ * // Custom allowed tags
+ * sanitize('<a href="http://example.com">Link</a>', {
+ *   plainTextOnly: false,
+ *   allowedTags: ['a'],
+ *   allowedAttributes: ['href']
+ * })
+ * // => '<a href="http://example.com">Link</a>'
+ */
+export declare const sanitize: (input: string | undefined | null, options?: SanitizeOptions) => string;
+/**
+ * Sanitizes data from HTTP responses
+ *
+ * This function recursively sanitizes all string values in an object or array.
+ * Useful for cleaning data received from external APIs before displaying it.
+ *
+ * Protection against:
+ * - Circular references: Uses WeakSet to detect and handle circular objects
+ * - Deep nesting attacks: Limits recursion depth to prevent DoS
+ * - XSS attacks: Sanitizes all string values
+ *
+ * @param data - The data to sanitize (can be any type)
+ * @param options - Sanitization options
+ * @param depth - Current recursion depth (internal use)
+ * @param seen - WeakSet to track visited objects (internal use)
+ * @returns Sanitized data with same structure
+ *
+ * @example
+ * sanitizeHttpResponse({
+ *   name: 'John <script>xss</script>',
+ *   nested: { title: 'Hello <b>world</b>' }
+ * })
+ * // => { name: 'John ', nested: { title: 'Hello <b>world</b>' } }
+ *
+ * @example
+ * // Handles circular references gracefully
+ * const obj = { name: 'Test' };
+ * obj.self = obj;
+ * sanitizeHttpResponse(obj)
+ * // => { name: 'Test', self: { name: 'Test' } } // circular ref broken
+ */
+export declare const sanitizeHttpResponse: (data: unknown, options?: SanitizeOptions, depth?: number, seen?: WeakSet<object>) => unknown;
+export {};

package/dist/renderer/utils/sanitize.native.d.ts

@@ -0,0 +1,69 @@
+/**
+ * React Native implementation of sanitization utilities
+ * Does not use DOMPurify as it depends on browser DOM
+ */
+/**
+ * Configuration for sanitization
+ */
+interface SanitizeOptions {
+    /**
+     * Allow only plain text (strip all HTML tags)
+     * @default true
+     */
+    plainTextOnly?: boolean;
+    /**
+     * Custom allowed tags (when plainTextOnly is false)
+     * Note: In React Native, HTML tags are always stripped
+     */
+    allowedTags?: string[];
+    /**
+     * Custom allowed attributes (when plainTextOnly is false)
+     * Note: In React Native, attributes are not applicable
+     */
+    allowedAttributes?: string[];
+}
+/**
+ * Sanitizes user input to prevent XSS attacks
+ *
+ * React Native implementation that strips all HTML tags and decodes entities.
+ * Since React Native doesn't render HTML, we focus on cleaning text content.
+ *
+ * @param input - The string to sanitize
+ * @param options - Sanitization options (maintained for API compatibility)
+ * @returns Sanitized string safe for rendering
+ *
+ * @example
+ * sanitize('<script>alert("xss")</script>Hello')
+ * // => 'Hello'
+ *
+ * @example
+ * sanitize('<b>Bold text</b><script>alert("xss")</script>')
+ * // => 'Bold text'
+ */
+export declare const sanitize: (input: string | undefined | null, _options?: SanitizeOptions) => string;
+/**
+ * Sanitizes data from HTTP responses
+ *
+ * This function recursively sanitizes all string values in an object or array.
+ * Useful for cleaning data received from external APIs before displaying it.
+ *
+ * Protection against:
+ * - Circular references: Uses WeakSet to detect and handle circular objects
+ * - Deep nesting attacks: Limits recursion depth to prevent DoS
+ * - XSS attacks: Sanitizes all string values
+ *
+ * @param data - The data to sanitize (can be any type)
+ * @param options - Sanitization options
+ * @param depth - Current recursion depth (internal use)
+ * @param seen - WeakSet to track visited objects (internal use)
+ * @returns Sanitized data with same structure
+ *
+ * @example
+ * sanitizeHttpResponse({
+ *   name: 'John <script>xss</script>',
+ *   nested: { title: 'Hello <b>world</b>' }
+ * })
+ * // => { name: 'John ', nested: { title: 'Hello world' } }
+ */
+export declare const sanitizeHttpResponse: (data: unknown, options?: SanitizeOptions, depth?: number, seen?: WeakSet<object>) => unknown;
+export {};

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

@@ -0,0 +1,27 @@
+import { Node } from '@xyflow/react';
+import { TreegeNodeData } from '../../shared/types/node';
+/**
+ * A renderer step — a contiguous slice of visible nodes that share the same
+ * `parentId` (group id) or no parent (orphan step).
+ *
+ * Steps are derived from the flow's visible nodes at render time; the editor's
+ * group nodes carry only metadata (label) and are no longer rendered.
+ */
+export type FlowStep = {
+    /**
+     * Group id owning the step, or null for orphan steps (nodes without `parentId`).
+     */
+    groupId: string | null;
+    /**
+     * The actual nodes (input + ui) rendered in this step, in flow order.
+     */
+    nodes: Node<TreegeNodeData>[];
+};
+/**
+ * Partition `visibleNodes` into ordered steps. A new step is started every
+ * time the `parentId` of the next renderable node changes (i.e. the flow
+ * crosses a group boundary, or moves between an orphan and a grouped node).
+ *
+ * Group nodes themselves are skipped — they're metadata only.
+ */
+export declare const computeSteps: (visibleNodes: Node<TreegeNodeData>[]) => FlowStep[];