treege 3.0.0-beta.7 → 3.0.0-beta.70

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,49 @@
+import { Node } from '@xyflow/react';
+import { 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
+ * @returns Promise with submission result
+ */
+export declare const submitFormData: (config: SubmitConfig, formValues: FormValues, inputNodes: Node<InputNodeData>[], headers?: HttpHeaders, baseUrl?: string) => 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[];