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

package/dist/shared/types/node.d.ts

@@ -1,6 +1,7 @@
 import { Edge, Node } from '@xyflow/react';
 import { INPUT_TYPE } from '../constants/inputType';
 import { UI_TYPE } from '../constants/uiType';
+import { SerializableFile } from './file';
 import { Translatable } from './translate';
 export type UIType = (typeof UI_TYPE)[keyof typeof UI_TYPE];
 export type InputType = (typeof INPUT_TYPE)[keyof typeof INPUT_TYPE];
@@ -18,10 +19,19 @@ export type InputOption = {
      * The label of the option, which can be translated
      */
     label: Translatable;
+    /**
+     * Optional secondary description, shown under the label (translatable)
+     */
+    description?: Translatable;
     /**
      * Whether the option is disabled and cannot be selected
      */
     disabled?: boolean;
+    /**
+     * Optional image for the option, stored as base64 data URL or remote URL.
+     * Currently displayed by radio inputs; uploads are automatically resized and compressed.
+     */
+    image?: string;
 };
 export type BaseNodeData = {
     /**
@@ -29,28 +39,24 @@ export type BaseNodeData = {
      */
     label?: Translatable;
 };
-export type FlowNodeData = BaseNodeData & {
-    /**
-     * The ID of the target node to connect to
-     */
-    targetId?: string;
-};
 export type GroupNodeData = BaseNodeData & {
     /**
      * A label for the group node, which can be translated
      */
     label: Translatable;
 };
-export type HttpHeader = {
-    /**
-     * The header key (e.g., "Authorization", "Content-Type")
-     */
-    key: string;
-    /**
-     * The header value
-     */
-    value: string;
-};
+/**
+ * HTTP headers as a plain object keyed by header name, e.g.
+ * `{ Authorization: "Bearer xyz", "Content-Type": "application/json" }`.
+ * Values support template variables like `{{fieldId}}`.
+ */
+export type HttpHeaders = Record<string, string>;
+/**
+ * Query parameters as a plain object keyed by parameter name, e.g.
+ * `{ limit: "10", sort: "asc" }`. Values support template variables like
+ * `{{fieldId}}`.
+ */
+export type QueryParams = Record<string, string>;
 export type HttpConfig = {
     /**
      * The HTTP method to use
@@ -63,11 +69,19 @@ export type HttpConfig = {
     /**
      * Custom headers for the HTTP request
      */
-    headers?: HttpHeader[];
+    headers?: HttpHeaders;
+    /**
+     * Query parameters appended to the URL (supports template variables like {{fieldId}})
+     */
+    queryParams?: QueryParams;
     /**
      * Request body (for POST/PUT/PATCH methods)
      */
     body?: string;
+    /**
+     * If true, automatically sends all form data as JSON body (overrides custom body)
+     */
+    sendAllFormValues?: boolean;
     /**
      * JSONPath or key to extract from the response
      * Examples: "data.users", "results[0].name"
@@ -85,6 +99,14 @@ export type HttpConfig = {
          * Path to the label field in response items
          */
         labelField?: string;
+        /**
+         * Path to the field used as the option description (optional)
+         */
+        descriptionField?: string;
+        /**
+         * Path to the field used as the option image — base64 data URL or remote URL (optional)
+         */
+        imageField?: string;
     };
     /**
      * Query parameter name for search (enables combobox with search)
@@ -100,6 +122,90 @@ export type HttpConfig = {
      */
     showLoading?: boolean;
 };
+/**
+ * Maps response item fields to InputOption properties.
+ * Each value is a path expression (e.g., "id", "user.name", "items[0].title").
+ */
+export type OptionsSourceMapping = {
+    /** Path to the field used as InputOption.value */
+    valueField: string;
+    /** Path to the field used as InputOption.label */
+    labelField: string;
+    /** Path to the field used as InputOption.description (optional) */
+    descriptionField?: string;
+    /** Path to the field used as InputOption.image (optional) */
+    imageField?: string;
+};
+/**
+ * Dynamic options source — fetches the option list from an HTTP endpoint
+ * at runtime. Applies to inputs that use options (radio, checkbox, select,
+ * autocomplete). When set, overrides the static `options` array.
+ */
+export type OptionsSource = {
+    /** API URL (supports template variables like {{fieldId}}) */
+    url?: string;
+    /** HTTP method */
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** Custom headers (merged with global headers; field-level wins) */
+    headers?: HttpHeaders;
+    /** Query parameters appended to the URL (supports template variables like {{fieldId}}) */
+    queryParams?: QueryParams;
+    /** Request body (for POST/PUT/PATCH; supports template variables) */
+    body?: string;
+    /** JSONPath to extract the array from the response (e.g., "data.users") */
+    responsePath?: string;
+    /** Field-to-property mapping for each response item */
+    mapping?: OptionsSourceMapping;
+};
+export type SubmitConfig = {
+    /**
+     * The HTTP method to use for form submission
+     */
+    method?: "POST" | "PUT" | "PATCH" | "DELETE";
+    /**
+     * The API URL to call on submit (supports template variables like {{fieldId}})
+     */
+    url?: string;
+    /**
+     * Custom headers for the HTTP request
+     */
+    headers?: HttpHeaders;
+    /**
+     * Query parameters appended to the URL (supports template variables like {{fieldId}})
+     */
+    queryParams?: QueryParams;
+    /**
+     * Free-form JSON template that defines the submitted payload. Field tokens
+     * sit inside string positions, e.g. `{"data": {"name": "{{firstName}}"}}`,
+     * where `{{token}}` is a field's node id (or its token-safe `name`) and is
+     * replaced by the field value with its JSON type preserved.
+     *
+     * This is the single source of truth for the payload: it is delivered to the
+     * `onSubmit` callback AND, when a `url` is configured, sent as the HTTP request
+     * body. Takes precedence over `sendAllFormValues`.
+     */
+    payloadTemplate?: string;
+    /**
+     * If true, automatically sends all form data as JSON body (overrides custom body)
+     */
+    sendAllFormValues?: boolean;
+    /**
+     * URL to redirect to after successful submission (supports template variables from response)
+     */
+    redirectUrl?: string;
+    /**
+     * Success message to display after successful submission (translatable)
+     */
+    successMessage?: Translatable;
+    /**
+     * Error message to display if submission fails (translatable)
+     */
+    errorMessage?: Translatable;
+    /**
+     * Whether to show a loading state while submitting
+     */
+    showLoading?: boolean;
+};
 export type InputNodeData = BaseNodeData & {
     /**
      * The name of the input field, used for identification and form submission
@@ -137,12 +243,20 @@ export type InputNodeData = BaseNodeData & {
      * Whether multiple selections are allowed (for select and checkbox types)
      */
     multiple?: boolean;
+    /**
+     * Visual variant (currently used by radio inputs)
+     */
+    variant?: "default" | "card";
+    /**
+     * Whether past dates should be disabled (for date and daterange types)
+     */
+    disablePast?: boolean;
     /**
      * The default value config for the input field
      */
     defaultValue?: null | {
         type?: "static" | "reference";
-        staticValue?: string | string[] | boolean;
+        staticValue?: string | string[] | boolean | SerializableFile | SerializableFile[];
         referenceField?: string;
         transformFunction?: null | "toString" | "toNumber" | "toBoolean" | "toArray" | "toObject";
         objectMapping?: Array<{
@@ -154,6 +268,28 @@ export type InputNodeData = BaseNodeData & {
      * HTTP configuration for the input field (used with type="http")
      */
     httpConfig?: HttpConfig;
+    /**
+     * Dynamic options source — fetches the option list from an HTTP endpoint
+     * at runtime. Used by option-based inputs (radio, checkbox, select, autocomplete).
+     * When set, overrides the static `options` array.
+     */
+    optionsSource?: OptionsSource;
+    /**
+     * Whether labels fetched from an API (dynamic `optionsSource` or an `http`
+     * input's `responseMapping`) are normalized to a uniform, readable Title Case
+     * form (e.g. "DUPONT JEAN" -> "Dupont Jean"). Manually-typed static option
+     * labels are never affected. Defaults to `true` when unset.
+     */
+    normalizeOptionLabels?: boolean;
+    /**
+     * Submit configuration for the input field (used with type="submit")
+     */
+    submitConfig?: SubmitConfig;
+    /**
+     * Optional illustrative image displayed above the input label.
+     * Stored as a base64 data URL (uploads are resized/compressed) or a remote URL.
+     */
+    image?: string;
 };
 export type UINodeData = BaseNodeData & {
     /**
@@ -164,7 +300,7 @@ export type UINodeData = BaseNodeData & {
 /**
  * Union type representing all possible node data types in the Treege system
  */
-export type TreegeNodeData = InputNodeData | UINodeData | FlowNodeData | GroupNodeData;
+export type TreegeNodeData = InputNodeData | UINodeData | GroupNodeData;
 /**
  * A TreegeNode represents a node in the flowchart with specific data and properties
  */

package/dist/shared/utils/httpRecord.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A single editable key/value row. Editor forms work on lists of these while
+ * the user types (they tolerate transient empty keys), then serialize back to
+ * the persisted `Record<string, string>` form via `entriesToRecord`.
+ */
+export type KeyValueEntry = {
+    key: string;
+    value: string;
+};
+/**
+ * Expand a `{ key: value }` record into editor rows, preserving insertion
+ * order. Returns an empty list for `undefined`.
+ */
+export declare const recordToEntries: (record?: Record<string, string>) => KeyValueEntry[];
+/**
+ * Collapse editor rows back into a `{ key: value }` record. Rows with an empty
+ * key are dropped (they're transient editing artifacts), and on duplicate keys
+ * the last occurrence wins.
+ */
+export declare const entriesToRecord: (entries?: KeyValueEntry[]) => Record<string, string>;

package/dist/shared/utils/inputTypeGuards.d.ts

@@ -0,0 +1,7 @@
+import { InputNodeData, TreegeNodeData } from '../types/node';
+/**
+ * Type guard: narrows the node `data` to an `InputNodeData` whose type
+ * supports an option list. After a truthy check, `data.options`,
+ * `data.optionsSource`, etc. are accessible without casts.
+ */
+export declare const isOptionsInputData: (data: TreegeNodeData | undefined) => data is InputNodeData;

package/dist/shared/utils/nodeTypeGuards.d.ts

@@ -1,5 +1,5 @@
 import { Node } from '@xyflow/react';
-import { FlowNodeData, GroupNodeData, InputNodeData, TreegeNode, UINodeData } from '../types/node';
+import { GroupNodeData, InputNodeData, TreegeNode, UINodeData } from '../types/node';
 /**
  * Type guard to check if a node is an InputNode
  * @param node
@@ -10,11 +10,6 @@ export declare const isInputNode: (node: TreegeNode | undefined) => node is Node
  * @param node
  */
 export declare const isUINode: (node: TreegeNode | undefined) => node is Node<UINodeData, "ui">;
-/**
- * Type guard to check if a node is a FlowNode
- * @param node
- */
-export declare const isFlowNode: (node: TreegeNode | undefined) => node is Node<FlowNodeData, "flow">;
 /**
  * Type guard to check if a node is a GroupNode
  * @param node

package/dist/shared/utils/normalizeLabel.d.ts

@@ -0,0 +1,22 @@
+import { Translatable } from '../types/translate';
+/**
+ * Normalizes a raw label string into a uniform, readable Title Case form.
+ *
+ * Designed for labels coming from an API where casing is often inconsistent
+ * (ALL CAPS, snake_case, kebab-case, camelCase). Each word gets an uppercase
+ * first letter and a lowercase remainder, with separators collapsed to single
+ * spaces:
+ *
+ *   "DUPONT JEAN"   -> "Dupont Jean"
+ *   "admin_user"    -> "Admin User"
+ *   "dateNaissance" -> "Date Naissance"
+ *
+ * Empty/whitespace-only input is returned unchanged.
+ */
+export declare const normalizeLabel: (text: string) => string;
+/**
+ * Applies {@link normalizeLabel} to every language entry of a `Translatable`
+ * label, preserving its shape. Labels are always the object form here — plain
+ * strings are coerced upstream by `normalizeFlowLabels` on ingestion.
+ */
+export declare const normalizeTranslatableLabel: (label: Translatable) => Translatable;

package/dist/shared/utils/translations.d.ts

@@ -21,7 +21,27 @@ export type TranslationKey = DotNotationKeys<typeof en>;
  * @param language - Optional preferred language (defaults to 'en')
  * @returns The translated string or empty string if none available
  */
-export declare const getTranslatedText: (text?: Translatable | string, language?: string) => string;
+export declare const getTranslatedText: (text?: Translatable, language?: string) => string;
+/**
+ * Reads the value of a translatable field for a given language while tolerating a
+ * value for a language. Returns "" when the value or the language entry is absent.
+ *
+ * Use this for editor inputs instead of `value?.[language]` so reads/writes stay
+ * consistent with {@link setTranslatableValue}.
+ */
+export declare const getTranslatableValue: (value: Translatable | undefined, language: string) => string;
+/**
+ * Sets `language` to `next` on a translatable field and returns a NEW Translatable,
+ * preserving the other language entries. Always use this when writing a
+ * translatable field from the editor rather than spreading the previous value
+ * inline.
+ *
+ * The `typeof === "object"` guard is purely defensive: the type system guarantees
+ * an object, but should a stray non-object (e.g. unsupported legacy string data)
+ * reach this at runtime, it is dropped rather than spread into indexed character
+ * keys (`"Hi"` → `{ "0": "H", "1": "i" }`).
+ */
+export declare const setTranslatableValue: (value: Translatable | undefined, language: string, next: string) => Translatable;
 /**
  * Get static translations for a specific language
  * Falls back to English if language not found