treege 2.1.0 → 3.0.0-beta.2

package/README.md

@@ -1,104 +1,418 @@
 <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="#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>
+  </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
 
-[![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)
+### 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
+- **Type-safe**: Full TypeScript 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)
+### 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
+- **Theme Support**: Dark/light mode out of the box
+
+### 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
 ```
 
-## Usage
+## Quick Start
 
-```typescript jsx
-import { Treege } from "treege";
+### Using the Editor
 
-const App = () => {
-  return <Treege />;
-};
+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>
 
-export default App;
+      {mode === "edit" ? (
+        <TreegeEditor flow={flow} onSave={setFlow} />
+      ) : (
+        <TreegeRenderer flows={flow} onSubmit={console.log} />
+      )}
+    </div>
+  );
+}
 ```
 
-### Options
+## Module Structure
+
+Treege provides three import paths for optimal bundle size:
 
-| 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                          |
+```tsx
+// Import everything (editor + renderer + types)
+import { TreegeEditor, TreegeRenderer } from "treege";
 
+// Import only the editor
+import { TreegeEditor } from "treege/editor";
 
-#### `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                                     |
+// Import only the renderer
+import { TreegeRenderer } from "treege/renderer";
+```
 
-#### `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` |
+## Node Types
 
-Backend model need to be compatible with the following interface:
+### Flow Node
+Navigation node that controls the flow between different parts of the tree.
 
-```typescript
-interface Workflow {
-  id: string;
-  name: string;
-  description: string;
-  tree: Tree;
+```tsx
+{
+  type: "flow",
+  data: {
+    targetId: "next-node-id",
+    label: "Continue"
+  }
 }
 ```
 
-`Tree` is a JSON object generated by `Treege` with the following interface:
+### Input Node
+Form input with validation, patterns, and conditional logic.
 
-```typescript
-interface Tree {
-  name: string;
-  attributes: any;
-  children: Tree[];
-  treeId?: string;
+```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"
+  }
 }
 ```
 
-## How use Treege data ?
+Supported input types: `text`, `email`, `password`, `number`, `textarea`, `select`, `radio`, `checkbox`, `switch`, `date`, `dateRange`, `time`, `timeRange`, `file`, `address`, `http`
 
-You can easily generate a form with the `React library` [treege-consumer](https://github.com/Tracktor/treege-consumer) or use our own application !
+### Group Node
+Container for organizing multiple nodes together.
+
+```tsx
+{
+  type: "group",
+  data: {
+    label: "Personal Information"
+  }
+}
+```
 
-## Local installation
+### JSON Node
+Store and manage JSON data within the tree.
 
-Clone the repository and install dependencies
+```tsx
+{
+  type: "json",
+  data: {
+    json: { key: "value" }
+  }
+}
+```
+
+### UI Node
+Display-only elements (titles, descriptions, separators).
+
+```tsx
+{
+  type: "ui",
+  data: {
+    type: "title",
+    label: "Welcome to the form"
+  }
+}
+```
+
+## 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"
+  }
+}
+```
 
-```console 
+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"
+    }
+  }
+}
+```
+
+## Customization
+
+### Custom Input Components
+
+Override default input renderers with your own:
+
+```tsx
+import { TreegeRenderer } from "treege/renderer";
+
+const CustomTextInput = ({ node }) => {
+  return <input className="my-custom-input" />;
+};
+
+<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;
+  }}
+/>
+```
+
+### Validation Modes
+
+Control when validation occurs:
+
+```tsx
+// Validate only on submit (default)
+<TreegeRenderer validationMode="onSubmit" />
+
+// Validate on every change
+<TreegeRenderer validationMode="onChange" />
+```
+
+## Examples
+
+Check out the `/example` directory for complete examples:
+
+```bash
+  # Run the example app
+  bun example
+```
+
+## 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                |
+
+### 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  |
+
+## 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)