treege 2.1.0 → 3.0.0-beta.10

package/README.md

@@ -1,104 +1,489 @@
 <div align="center">
   <img alt="Treege" src="https://user-images.githubusercontent.com/108873902/189673125-5d1fdaf3-82d1-486f-bb16-01b0554bd4f1.png" style="padding: 20px;" width="auto" height="100" />
-  <p><strong>Treege is a tools for decision tree generator</strong></p>
+
+  <h1>Treege</h1>
+  <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)
+
+  <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="#examples">Examples</a>
+  </p>
 </div>
 
-[![npm version](https://badge.fury.io/js/treege.svg)](https://badge.fury.io/js/treege)
+---
+
+## Overview
+
+Treege is a modern React library for creating and rendering interactive decision trees. Built on top of ReactFlow, it provides a complete solution for building complex form flows, decision logic, and conditional workflows with an intuitive visual editor.
+
+## Features
+
+### Visual Editor (`treege/editor`)
+- **Node-based Interface**: Drag-and-drop editor powered by ReactFlow
+- **4 Node Types**: Flow, Group, Input, and UI nodes
+- **Conditional Edges**: Advanced logic with AND/OR operators (`===`, `!==`, `>`, `<`, `>=`, `<=`)
+- **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
 
-[![Video Thumbnail](https://img.youtube.com/vi/YOUTUBE_VIDEO_ID/0.jpg)](https://user-images.githubusercontent.com/108873902/184317603-61ceafc6-a326-49b2-b0de-ffda9cf9c75e.mov)
+### Runtime Renderer (`treege/renderer`)
+- **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
+- **HTTP Integration**: Built-in API integration with response mapping and search functionality
+- **Advanced Validation**: Required fields, pattern matching, custom validation functions
+- **Conditional Logic**: Dynamic field visibility based on user input and conditional edges
+- **Web & Native**: Both web (React) and React Native renderer implementations
+- **Fully Customizable**: Override any component (FormWrapper, Group, Inputs, SubmitButton, UI elements)
+- **Theme Support**: Dark/light mode out of the box
+- **Google API Integration**: Address autocomplete support
 
-- [Installation](#Installation)
-- [Usage](#Usage)
-  - [Options](#Options)
-- [Generate form from Treege data](#Generate-form-from-Treege-data)
-- [Local installation](#local-installation)
-- [Available Scripts](#Available-Scripts)
-    - [yarn dev](#yarn-dev)
-    - [yarn build](#yarn-build)
-    - [yarn preview](#yarn-preview)
-- [Convention](#Convention)
+### Developer Experience
+- **Modular**: Import only what you need (editor, renderer, or both)
+- **Modern Stack**: React 18/19, TailwindCSS 4, TypeScript 5
+- **Well-typed**: Comprehensive TypeScript definitions
+- **Production Ready**: Battle-tested and actively maintained
 
 ## Installation
 
-```console
+```bash
+# npm
+npm install treege
+
+# pnpm
+pnpm add treege
+
+# yarn
 yarn add treege
+
+# bun
+bun add treege
+```
+
+## Quick Start
+
+### Using the Editor
+
+Create and edit decision trees visually:
+
+```tsx
+import { TreegeEditor } from "treege/editor";
+import type { Flow } from "treege";
+
+function App() {
+  const [flow, setFlow] = useState<Flow | null>(null);
+
+  const handleSave = (updatedFlow: Flow) => {
+    setFlow(updatedFlow);
+    console.log("Decision tree saved:", updatedFlow);
+  };
+
+  return (
+    <TreegeEditor
+      flow={flow}
+      onSave={handleSave}
+    />
+  );
+}
+```
+
+### Using the Renderer
+
+Render interactive forms from decision trees:
+
+```tsx
+import { TreegeRenderer } from "treege/renderer";
+import type { Flow, FormValues } from "treege";
+
+function App() {
+  const flow: Flow = {
+    id: "flow-1",
+    nodes: [
+      {
+        id: "start",
+        type: "input",
+        data: {
+          name: "username",
+          label: "Enter your username",
+          required: true
+        }
+      }
+    ],
+    edges: []
+  };
+
+  const handleSubmit = (values: FormValues) => {
+    console.log("Form submitted:", values);
+  };
+
+  return (
+    <TreegeRenderer
+      flows={flow}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+### Using Both Together
+
+```tsx
+import { TreegeEditor } from "treege/editor";
+import { TreegeRenderer } from "treege/renderer";
+import { useState } from "react";
+
+function App() {
+  const [flow, setFlow] = useState(null);
+  const [mode, setMode] = useState<"edit" | "preview">("edit");
+
+  return (
+    <div>
+      <button onClick={() => setMode(mode === "edit" ? "preview" : "edit")}>
+        {mode === "edit" ? "Preview" : "Edit"}
+      </button>
+
+      {mode === "edit" ? (
+        <TreegeEditor flow={flow} onSave={setFlow} />
+      ) : (
+        <TreegeRenderer flows={flow} onSubmit={console.log} />
+      )}
+    </div>
+  );
+}
+```
+
+## Module Structure
+
+Treege provides three import paths for optimal bundle size:
+
+```tsx
+// Import everything (editor + renderer + types)
+import { TreegeEditor, TreegeRenderer } from "treege";
+
+// Import only the editor
+import { TreegeEditor } from "treege/editor";
+
+// Import only the renderer
+import { TreegeRenderer } from "treege/renderer";
+```
+
+## Node Types
+
+### Flow Node
+Navigation node that controls the flow between different parts of the tree.
+
+```tsx
+{
+  type: "flow",
+  data: {
+    targetId: "next-node-id",
+    label: "Continue"
+  }
+}
+```
+
+### Input Node
+Form input with validation, patterns, and conditional logic.
+
+```tsx
+{
+  type: "input",
+  data: {
+    type: "text",
+    name: "email",
+    label: "Email Address",
+    required: true,
+    pattern: "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$",
+    errorMessage: "Please enter a valid email"
+  }
+}
+```
+
+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.
+
+```tsx
+{
+  type: "group",
+  data: {
+    label: "Personal Information"
+  }
+}
+```
+
+### UI Node
+Display-only elements for visual organization and content display.
+
+```tsx
+{
+  type: "ui",
+  data: {
+    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:
+
+```tsx
+{
+  type: "conditional",
+  data: {
+    conditions: [
+      {
+        field: "age",
+        operator: ">=",
+        value: "18"
+      },
+      {
+        field: "country",
+        operator: "===",
+        value: "US"
+      }
+    ],
+    logicalOperator: "AND"
+  }
+}
+```
+
+Supported operators: `===`, `!==`, `>`, `<`, `>=`, `<=`
+
+## Translation Support
+
+Treege supports multiple languages out of the box:
+
+```tsx
+{
+  type: "input",
+  data: {
+    label: {
+      en: "First Name",
+      fr: "Prénom",
+      es: "Nombre"
+    }
+  }
+}
 ```
 
-## Usage
+## Customization
+
+### Custom Input Components
+
+Override default input renderers with your own:
 
-```typescript jsx
-import { Treege } from "treege";
+```tsx
+import { TreegeRenderer } from "treege/renderer";
 
-const App = () => {
-  return <Treege />;
+const CustomTextInput = ({ node }) => {
+  return <input className="my-custom-input" />;
 };
 
-export default App;
+<TreegeRenderer
+  flows={flow}
+  components={{
+    inputs: {
+      text: CustomTextInput
+    }
+  }}
+/>
+```
+
+### Custom Validation
+
+Add custom validation logic:
+
+```tsx
+<TreegeRenderer
+  flows={flow}
+  validate={(values, visibleNodes) => {
+    const errors = {};
+
+    if (values.password !== values.confirmPassword) {
+      errors.confirmPassword = "Passwords must match";
+    }
+
+    return errors;
+  }}
+/>
 ```
 
-### Options
+### Validation Modes
 
-| Props         | Type   | Default   | Required | Detail                                                                                        |
-|---------------|--------|-----------|----------|-----------------------------------------------------------------------------------------------|
-| backendConfig | object | undefined | false    | Backend configuration. Only necessary if you want backend communication.                      |
-| initialTreeId | string | undefined | false    | If provided, this will fetch initial tree id. Cannot provided with `initialTree` in same time |
-| initialTree   | object | undefined | false    | Initial tree data. Cannot provided with `initialTreeId` in same time                          |
+Control when validation occurs:
 
+```tsx
+// Validate only on submit (default)
+<TreegeRenderer validationMode="onSubmit" />
 
-#### `backendConfig`
-| Props     | Type   | Default   | Required | Detail                                                      |
-|-----------|--------|-----------|----------|-------------------------------------------------------------|
-| baseUrl   | string | undefined | true     | Base url for API communication. ex : https://api.treege.com |
-| authToken | string | undefined | false    | Authentication token                                        |
-| endpoints | object | undefined | false    | Endpoints configuration                                     |
+// Validate on every change
+<TreegeRenderer validationMode="onChange" />
+```
 
-#### `endpoints`
-| Props     | Type   | Default   | Required        | Detail                                                      |
-|-----------|--------|-----------|-----------------|-------------------------------------------------------------|
-| workflow  | string | undefined | "/v1/workflow"  | Endpoint for `get/post/patch` single `workflow`             |
-| workflows | string | undefined | "/v1/workflows" | Endpoint for get all workflows. It is a array on `workflow` |
+### HTTP Input Integration
 
-Backend model need to be compatible with the following interface:
+Use the HTTP input type to fetch and map data from APIs:
 
-```typescript
-interface Workflow {
-  id: string;
-  name: string;
-  description: string;
-  tree: Tree;
+```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
+    }
+  }
 }
 ```
 
-`Tree` is a JSON object generated by `Treege` with the following interface:
+### Global Configuration
+
+Configure the renderer globally using the TreegeConfigProvider:
 
-```typescript
-interface Tree {
-  name: string;
-  attributes: any;
-  children: Tree[];
-  treeId?: string;
+```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>
+  );
 }
 ```
 
-## How use Treege data ?
+### 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
+```
+
+## API Reference
+
+### TreegeEditor Props
 
-You can easily generate a form with the `React library` [treege-consumer](https://github.com/Tracktor/treege-consumer) or use our own application !
+| 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                |
 
-## Local installation
+### TreegeRenderer Props
 
-Clone the repository and install dependencies
+| 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  |
 
-```console 
+## Development
+
+```bash
+# Install dependencies
 yarn install
+
+# Start dev server
+yarn dev
+
+# Build library
+yarn build
+
+# Run linter and type check
+yarn lint
+
+# Preview build
+yarn preview
 ```
-Locally preview production build
 
-## Convention
+## Tech Stack
+
+- **React** 18/19 - UI library
+- **TypeScript** - Type safety
+- **TailwindCSS** 4 - Styling
+- **ReactFlow** - Node-based UI
+- **Radix UI** - Accessible components
+- **Zustand** - State management
+- **Vite** - Build tool
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+ISC
+
+## Credits
 
-- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
-- [Versioning](https://semver.org)
-- [Conventional Commits](https://www.conventionalcommits.org)
+Created and maintained by [Mickaël Austoni](https://github.com/Tracktor)
 
-## Type Definitions
+## Support
 
-This library uses type definitions from [@tracktor/types-treege](https://www.npmjs.com/package/@tracktor/types-treege)
+- [GitHub Issues](https://github.com/Tracktor/treege/issues)
+- [Repository](https://github.com/Tracktor/treege)