treege 3.0.0-beta.4 → 3.0.0-beta.40

package/LICENSE

@@ -1,15 +1,21 @@
-The ISC License (ISC)
+MIT License
 
-Copyright (C) 2022 Tracktor
+Copyright (c) 2025 Tracktor
 
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
-OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
-CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,14 +5,16 @@
   <p><strong>Build powerful decision trees with a visual node-based editor</strong></p>
 
   [![npm version](https://badge.fury.io/js/treege.svg)](https://badge.fury.io/js/treege)
-  [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
   <p>
+    <a href="https://treege.io/">🌐 Website</a> •
+    <a href="https://treege.io/playground/">🎮 Playground</a> •
     <a href="#features">Features</a> •
     <a href="#installation">Installation</a> •
     <a href="#quick-start">Quick Start</a> •
-    <a href="#documentation">Documentation</a> •
-    <a href="#examples">Examples</a>
+    <a href="#examples">Examples</a> •
+    <a href="./AI_GENERATION.md">🪄 AI Generation</a>
   </p>
 </div>
 
@@ -26,17 +28,27 @@ Treege is a modern React library for creating and rendering interactive decision
 
 ### Visual Editor (`treege/editor`)
 - **Node-based Interface**: Drag-and-drop editor powered by ReactFlow
-- **5 Node Types**: Flow, Group, Input, JSON, and UI nodes
-- **Conditional Edges**: Advanced logic with AND/OR operators
-- **Multi-language Support**: Built-in translation system
+- **4 Node Types**: Flow, Group, Input, and UI nodes
+- **Conditional Edges**: Advanced logic with AND/OR operators (`===`, `!==`, `>`, `<`, `>=`, `<=`)
+- **AI-Powered Generation**: Generate decision trees from natural language descriptions using Gemini, OpenAI, DeepSeek, or Claude ([Learn more](./AI_GENERATION.md))
+- **Multi-language Support**: Built-in translation system for all labels
 - **Type-safe**: Full TypeScript support
+- **Mini-map & Controls**: Navigation tools for complex trees
+- **Theme Support**: Dark/light mode with customizable backgrounds
 
 ### Runtime Renderer (`treege/renderer`)
-- **Form Generation**: Automatically render forms from decision trees
-- **Validation**: Built-in required and pattern validation
-- **Conditional Logic**: Dynamic field visibility based on user input
-- **Customizable**: Override default components with your own
+- **Production Ready**: Full-featured form generation and validation system
+- **16 Input Types**: text, number, select, checkbox, radio, date, daterange, time, timerange, file, address, http, textarea, password, switch, autocomplete, and hidden
+- **Cross-Platform**: Full support for both React Web and React Native with dedicated implementations
+- **HTTP Integration**: Built-in API integration with response mapping and search functionality
+- **Advanced Validation**: Required fields, pattern matching, custom validation functions
+- **Security**: Built-in input sanitization to prevent XSS attacks
+- **Enhanced Error Messages**: Clear, user-friendly error messages for HTTP inputs and validation
+- **Conditional Logic**: Dynamic field visibility based on user input and conditional edges
+- **Fully Customizable**: Override any component (FormWrapper, Group, Inputs, SubmitButton, UI elements)
+- **Optional Dependencies**: Graceful degradation when optional packages like `react-native-document-picker` aren't installed
 - **Theme Support**: Dark/light mode out of the box
+- **Google API Integration**: Address autocomplete support
 
 ### Developer Experience
 - **Modular**: Import only what you need (editor, renderer, or both)
@@ -154,7 +166,7 @@ function App() {
 
 ## Module Structure
 
-Treege provides three import paths for optimal bundle size:
+Treege provides multiple import paths for optimal bundle size:
 
 ```tsx
 // Import everything (editor + renderer + types)
@@ -163,10 +175,167 @@ import { TreegeEditor, TreegeRenderer } from "treege";
 // Import only the editor
 import { TreegeEditor } from "treege/editor";
 
-// Import only the renderer
+// Import only the web renderer
 import { TreegeRenderer } from "treege/renderer";
+
+// Import only the React Native renderer
+import { TreegeRenderer } from "treege/renderer-native";
 ```
 
+## React Native Support
+
+Treege 3.0 includes full React Native support with a dedicated renderer implementation.
+
+### Installation for React Native
+
+```bash
+# Install Treege
+npm install treege
+
+# Install peer dependencies
+npm install react-native
+
+# Optional: Install for file input support
+npm install react-native-document-picker
+```
+
+### Basic Usage
+
+```tsx
+import { TreegeRenderer } from "treege/renderer-native";
+import type { Flow, FormValues } from "treege";
+
+function App() {
+  const flow: Flow = {
+    id: "flow-1",
+    nodes: [
+      {
+        id: "name",
+        type: "input",
+        data: {
+          type: "text",
+          name: "fullName",
+          label: "Full Name",
+          required: true
+        }
+      },
+      {
+        id: "email",
+        type: "input",
+        data: {
+          type: "text",
+          name: "email",
+          label: "Email",
+          required: true,
+          pattern: "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"
+        }
+      }
+    ],
+    edges: []
+  };
+
+  const handleSubmit = (values: FormValues) => {
+    console.log("Form submitted:", values);
+  };
+
+  return (
+    <TreegeRenderer
+      flows={flow}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+### Custom Styling
+
+You can customize the appearance using the `style` and `contentContainerStyle` props:
+
+```tsx
+<TreegeRenderer
+  flows={flow}
+  onSubmit={handleSubmit}
+  style={{ flex: 1, backgroundColor: "#f5f5f5" }}
+  contentContainerStyle={{ padding: 20 }}
+/>
+```
+
+### Custom Components
+
+Override default components with your own React Native components:
+
+```tsx
+import { Text, TextInput, View } from "react-native";
+import { TreegeRenderer } from "treege/renderer-native";
+
+const CustomTextInput = ({ value, setValue, label, error }) => {
+  return (
+    <View style={{ marginBottom: 16 }}>
+      <Text style={{ fontSize: 14, marginBottom: 4 }}>{label}</Text>
+      <TextInput
+        value={value}
+        onChangeText={setValue}
+        style={{
+          borderWidth: 1,
+          borderColor: error ? "red" : "#ccc",
+          padding: 10,
+          borderRadius: 8
+        }}
+      />
+      {error && <Text style={{ color: "red", fontSize: 12 }}>{error}</Text>}
+    </View>
+  );
+};
+
+<TreegeRenderer
+  flows={flow}
+  components={{
+    inputs: {
+      text: CustomTextInput
+    }
+  }}
+/>
+```
+
+### Supported Input Types
+
+The React Native renderer includes default implementations for all input types:
+
+**Fully Implemented (Vanilla React Native)**:
+- `text`, `number`, `textarea`, `password`
+- `checkbox`, `switch`, `hidden`
+
+**With Optional Dependencies** (gracefully degrades if not installed):
+- `file` - Requires [react-native-document-picker](https://github.com/rnmods/react-native-document-picker) (optional)
+
+**Requires Custom Implementation** (placeholder provided):
+- `select`, `radio`, `autocomplete`
+- `date`, `daterange`, `time`, `timerange`
+- `address`, `http`
+
+You can implement these inputs using popular React Native libraries:
+- [@react-native-picker/picker](https://github.com/react-native-picker/picker) for `select` and `radio`
+- [react-native-date-picker](https://github.com/henninghall/react-native-date-picker) for `date` and `time` inputs
+- [@react-native-community/google-places-autocomplete](https://github.com/FaridSafi/react-native-google-places-autocomplete) for `address`
+
+### API Reference
+
+The React Native renderer shares the same API as the web renderer, with some platform-specific props:
+
+| Prop                    | Type                                        | Default      | Description                                                |
+|-------------------------|---------------------------------------------|--------------|------------------------------------------------------------|
+| `flows`                 | `Flow \| Flow[] \| null`                    | -            | Decision tree to render (single Flow or array of Flows)    |
+| `onSubmit`              | `(values: FormValues, meta?: Meta) => void` | -            | Form submission handler (meta includes HTTP response data) |
+| `onChange`              | `(values: FormValues) => void`              | -            | Form change handler                                        |
+| `validate`              | `(values, nodes) => Record<string, string>` | -            | Custom validation function                                 |
+| `initialValues`         | `FormValues`                                | `{}`         | Initial form values                                        |
+| `components`            | `TreegeRendererComponents`                  | -            | Custom component overrides                                 |
+| `language`              | `string`                                    | `"en"`       | UI language                                                |
+| `validationMode`        | `"onSubmit" \| "onChange"`                  | `"onSubmit"` | When to validate                                           |
+| `googleApiKey`          | `string`                                    | -            | API key for address input                                  |
+| `style`                 | `ViewStyle`                                 | -            | ScrollView style (RN only)                                 |
+| `contentContainerStyle` | `ViewStyle`                                 | -            | Content container style (RN)                               |
+
 ## Node Types
 
 ### Flow Node
@@ -199,7 +368,7 @@ Form input with validation, patterns, and conditional logic.
 }
 ```
 
-Supported input types: `text`, `email`, `password`, `number`, `textarea`, `select`, `radio`, `checkbox`, `switch`, `date`, `dateRange`, `time`, `timeRange`, `file`, `address`, `http`
+Supported input types: `text`, `number`, `textarea`, `password`, `select`, `radio`, `checkbox`, `switch`, `autocomplete`, `date`, `daterange`, `time`, `timerange`, `file`, `address`, `http`, `hidden`
 
 ### Group Node
 Container for organizing multiple nodes together.
@@ -213,31 +382,23 @@ Container for organizing multiple nodes together.
 }
 ```
 
-### JSON Node
-Store and manage JSON data within the tree.
-
-```tsx
-{
-  type: "json",
-  data: {
-    json: { key: "value" }
-  }
-}
-```
-
 ### UI Node
-Display-only elements (titles, descriptions, separators).
+Display-only elements for visual organization and content display.
 
 ```tsx
 {
   type: "ui",
   data: {
-    type: "title",
+    type: "title", // or "divider"
     label: "Welcome to the form"
   }
 }
 ```
 
+Supported UI types:
+- `title` - Display headings and titles
+- `divider` - Visual separator between sections
+
 ## Conditional Edges
 
 Create dynamic flows with conditional logic:
@@ -336,40 +497,135 @@ Control when validation occurs:
 <TreegeRenderer validationMode="onChange" />
 ```
 
+### HTTP Input Integration
+
+Use the HTTP input type to fetch and map data from APIs:
+
+```tsx
+{
+  type: "input",
+  data: {
+    type: "http",
+    name: "country",
+    label: "Select your country",
+    httpConfig: {
+      method: "GET",
+      url: "https://api.example.com/countries",
+      responsePath: "$.data.countries", // JSONPath to extract data
+      mapping: {
+        label: "name",
+        value: "code"
+      },
+      searchParam: "query", // Enable search functionality
+      fetchOnMount: true
+    }
+  }
+}
+```
+
+### Global Configuration
+
+Configure the renderer globally using the TreegeConfigProvider:
+
+```tsx
+import { TreegeConfigProvider } from "treege/renderer";
+
+function App() {
+  return (
+    <TreegeConfigProvider
+      config={{
+        language: "fr",
+        googleApiKey: "your-google-api-key",
+        components: {
+          // Your custom components
+        }
+      }}
+    >
+      <TreegeRenderer flows={flow} />
+    </TreegeConfigProvider>
+  );
+}
+```
+
+### Programmatic Control
+
+Use the `useTreegeRenderer` hook for programmatic control:
+
+```tsx
+import { useTreegeRenderer } from "treege/renderer";
+
+function CustomForm() {
+  const { values, setFieldValue, submit, reset } = useTreegeRenderer();
+
+  return (
+    <div>
+      <button onClick={() => setFieldValue("email", "test@example.com")}>
+        Prefill Email
+      </button>
+      <button onClick={submit}>Submit</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
+}
+```
+
 ## Examples
 
 Check out the `/example` directory for complete examples:
 
 ```bash
-  # Run the example app
-  bun example
+# Run the example app
+bun example
 ```
 
+### Available Example URLs
+
+Once the development server is running, you can access these examples:
+
+- **Default Example**: [http://localhost:5173/](http://localhost:5173/)
+  - Basic demonstration of Treege functionality
+
+- **Demo Example**: [http://localhost:5173/example](http://localhost:5173/example)
+  - Full featured demo showcasing the library capabilities
+
+- **All Inputs Example**: [http://localhost:5173/example-all-inputs](http://localhost:5173/example-all-inputs)
+  - Comprehensive showcase of all 16 input types
+
+- **Custom Input Example**: [http://localhost:5173/example-custom-input](http://localhost:5173/example-custom-input)
+  - Demonstrates how to create and integrate custom input components
+
+- **TreegeConfigProvider Example**: [http://localhost:5173/example-treege-config-provider](http://localhost:5173/example-treege-config-provider)
+  - Shows global configuration with TreegeConfigProvider
+
 ## API Reference
 
 ### TreegeEditor Props
 
-| Prop       | Type                   | Default  | Description                 |
-|------------|------------------------|----------|-----------------------------|
-| `flow`     | `Flow \| null`         | `null`   | Initial decision tree       |
-| `onSave`   | `(flow: Flow) => void` | -        | Callback when tree is saved |
-| `language` | `string`               | `"en"`   | UI language                 |
-| `theme`    | `"light" \| "dark"`    | `"dark"` | Editor theme                |
+| Prop           | Type                                     | Default  | Description                                                                    |
+|----------------|------------------------------------------|----------|--------------------------------------------------------------------------------|
+| `flow`         | `Flow \| null`                           | `null`   | Initial decision tree                                                          |
+| `onSave`       | `(flow: Flow) => void`                   | -        | Callback when tree is saved                                                    |
+| `onExportJson` | `() => { nodes: Node[]; edges: Edge[] }` | -        | Callback for exporting JSON data                                               |
+| `language`     | `string`                                 | `"en"`   | UI language                                                                    |
+| `theme`        | `"light" \| "dark"`                      | `"dark"` | Editor theme                                                                   |
+| `aiConfig`     | `AIConfig`                               | -        | AI configuration for tree generation (see [AI Generation](./AI_GENERATION.md)) |
+| `className`    | `string`                                 | -        | Additional CSS class names for custom styling                                  |
 
 ### TreegeRenderer Props
 
-| Prop             | Type                                        | Default      | Description                |
-|------------------|---------------------------------------------|--------------|----------------------------|
-| `flows`          | `Flow \| null`                              | -            | Decision tree to render    |
-| `onSubmit`       | `(values: FormValues) => void`              | -            | Form submission handler    |
-| `onChange`       | `(values: FormValues) => void`              | -            | Form change handler        |
-| `validate`       | `(values, nodes) => Record<string, string>` | -            | Custom validation function |
-| `initialValues`  | `FormValues`                                | `{}`         | Initial form values        |
-| `components`     | `RendererComponents`                        | -            | Custom component overrides |
-| `language`       | `string`                                    | `"en"`       | UI language                |
-| `validationMode` | `"onSubmit" \| "onChange"`                  | `"onSubmit"` | When to validate           |
-| `theme`          | `"light" \| "dark"`                         | `"dark"`     | Renderer theme             |
-| `googleApiKey`   | `string`                                    | -            | API key for address input  |
+| Prop             | Type                                        | Default      | Description                                                |
+|------------------|---------------------------------------------|--------------|------------------------------------------------------------|
+| `flows`          | `Flow \| Flow[] \| null`                    | -            | Decision tree to render (single Flow or array of Flows)    |
+| `onSubmit`       | `(values: FormValues, meta?: Meta) => void` | -            | Form submission handler (meta includes HTTP response data) |
+| `onChange`       | `(values: FormValues) => void`              | -            | Form change handler                                        |
+| `validate`       | `(values, nodes) => Record<string, string>` | -            | Custom validation function                                 |
+| `initialValues`  | `FormValues`                                | `{}`         | Initial form values                                        |
+| `components`     | `TreegeRendererComponents`                  | -            | Custom component overrides                                 |
+| `language`       | `string`                                    | `"en"`       | UI language                                                |
+| `validationMode` | `"onSubmit" \| "onChange"`                  | `"onSubmit"` | When to validate                                           |
+| `theme`          | `"light" \| "dark"`                         | `"dark"`     | Renderer theme                                             |
+| `googleApiKey`   | `string`                                    | -            | API key for address input                                  |
+| `className`      | `string`                                    | -            | Additional CSS class names for custom styling              |
 
 ## Development
 
@@ -392,12 +648,10 @@ yarn preview
 
 ## Tech Stack
 
-- **React** 18/19 - UI library
+- **React** - UI library
 - **TypeScript** - Type safety
 - **TailwindCSS** 4 - Styling
 - **ReactFlow** - Node-based UI
-- **Radix UI** - Accessible components
-- **Zustand** - State management
 - **Vite** - Build tool
 
 ## Contributing
@@ -406,11 +660,11 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 
-ISC
+MIT
 
 ## Credits
 
-Created and maintained by [Mickaël Austoni](https://github.com/Tracktor)
+Created and maintained by [Mickaël Austoni](https://github.com/MickaelAustoni)
 
 ## Support