treege 3.0.0-beta.9 → 3.0.0-beta.90

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

@@ -0,0 +1,177 @@
+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;
+/**
+ * Parse a response body as JSON without throwing. Returns a discriminated
+ * result so callers can branch declaratively instead of wrapping a `let` in
+ * try/catch. A relative url resolved against the app origin (no baseUrl) or an
+ * auth redirect returns an HTML page, which `JSON.parse` would otherwise reject
+ * with a cryptic "Unexpected token '<'".
+ *
+ * @param text - The raw response body
+ * @returns `{ ok: true, value }` on success, `{ ok: false }` on parse failure
+ */
+export declare const tryParseJson: (text: string) => {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+/**
+ * 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/jsonTemplate.d.ts

@@ -0,0 +1,30 @@
+import { Node } from '@xyflow/react';
+import { FormValues } from '../types/renderer';
+import { InputNodeData } from '../../shared/types/node';
+/**
+ * Resolve a free-form JSON template into the actual payload.
+ *
+ * The template is valid JSON where field tokens sit inside string positions,
+ * e.g. `{ "data": { "name": "{{firstName}}", "age": "{{age}}" } }`. The template
+ * is parsed first, then each `"{{token}}"` is replaced by the matching field
+ * value (`token` = a field's node id, or its token-safe `name`), preserving the
+ * value's JSON type. Tokens may also be used inside object keys.
+ *
+ * @param template - The JSON template string
+ * @param formValues - Current form values, keyed by node id
+ * @param inputNodes - Input nodes, used to also expose values by field name
+ * @returns The resolved payload, or `undefined` when the template is empty or
+ *          not valid JSON (e.g. while the user is still typing)
+ */
+export declare const resolveJsonTemplate: (template: string | undefined, formValues: FormValues, inputNodes: Node<InputNodeData>[]) => unknown;
+/**
+ * Resolve a JSON template and serialize it to a string, ready to be used as an
+ * HTTP request body. Returns `undefined` when the template is empty or invalid
+ * JSON (so the caller can omit the body).
+ */
+export declare const resolveTemplateToJson: (template: string | undefined, formValues: FormValues, inputNodes: Node<InputNodeData>[]) => string | undefined;
+/**
+ * Whether a non-empty JSON template is syntactically valid JSON. Used by the
+ * editor to surface a clear error instead of silently falling back at runtime.
+ */
+export declare const isJsonTemplateValid: (template: string | undefined) => boolean;

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

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[];

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

@@ -0,0 +1,50 @@
+import { Node } from '@xyflow/react';
+import { ExtraPayload, FormValues } from '../types/renderer';
+import { HttpHeaders, InputNodeData, SubmitConfig } from '../../shared/types/node';
+/**
+ * Result of a form submission
+ */
+export interface SubmitResult {
+    /**
+     * Whether the submission was successful
+     */
+    success: boolean;
+    /**
+     * Response data from the server
+     */
+    data?: unknown;
+    /**
+     * Error message if submission failed
+     */
+    error?: string;
+    /**
+     * URL to redirect to (if configured)
+     */
+    redirectUrl?: string;
+}
+/**
+ * Submit form data using the provided submit configuration
+ *
+ * This function handles:
+ * - Template variable replacement in URL, body, and headers
+ * - HTTP request to the configured endpoint
+ * - Response parsing
+ * - Redirect URL generation with response data
+ *
+ * @param config - Submit configuration from the submit button node
+ * @param formValues - Current form values
+ * @param inputNodes - All input nodes (required when sendAllFormValues is true)
+ * @param headers
+ * @param baseUrl - Base URL prepended to a relative submit url
+ * @param extraPayload - Consumer-injected fields merged into the request body
+ * @returns Promise with submission result
+ */
+export declare const submitFormData: (config: SubmitConfig, formValues: FormValues, inputNodes: Node<InputNodeData>[], headers?: HttpHeaders, baseUrl?: string, extraPayload?: ExtraPayload) => Promise<SubmitResult>;
+/**
+ * Perform redirect to the specified URL
+ *
+ * Handles both relative and absolute URLs
+ *
+ * @param url - The URL to redirect to
+ */
+export declare const redirect: (url: string) => void;

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

@@ -0,0 +1,17 @@
+import { Node } from '@xyflow/react';
+import { FormValues, MissingDependency } from '../types/renderer';
+import { InputNodeData } from '../../shared/types/node';
+/**
+ * The node ids an input's dynamic request depends on — every `{{nodeId}}`
+ * referenced in its `httpConfig` or `optionsSource` url, query-param values, or
+ * body. These are the fields that must be filled before the input can fetch its
+ * options. Headers are excluded: they carry auth/global values, not user-filled
+ * form fields.
+ */
+export declare const getTemplateDependencyIds: (node: Node<InputNodeData>) => string[];
+/**
+ * The input's template dependencies that are not yet filled, paired with the
+ * referenced field's translated label. Computed centrally in `useRenderNode`
+ * and passed to every input renderer as `extra.missingDependencies`.
+ */
+export declare const getMissingDependencies: (node: Node<InputNodeData>, formValues: FormValues, inputNodes: Node<InputNodeData>[], language: string) => MissingDependency[];