npm - treege - Versions diffs - 3.0.0-beta.62 → 3.0.0-beta.64 - Mend

treege 3.0.0-beta.62 → 3.0.0-beta.64

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/README.md CHANGED Viewed

@@ -45,8 +45,9 @@ Treege is a modern React library for creating and rendering interactive decision
 - **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
-- **Multi-Step Forms**: Group nodes are automatically turned into navigable steps with Back/Continue controls
-- **Loading State**: Built-in `isLoading` prop renders a customizable skeleton while the flow is being fetched
+- **Multi-Step Forms**: Group nodes are automatically turned into navigable steps with Back/Continue controls, an `onBack` bridge to outer flows, and external-button submission via `formId`
+- **Edit Mode**: Pre-fill with `initialValues` (accepts name keys, reactive) to round-trip and edit previously submitted records
+- **Loading State**: Built-in `isLoading` prop renders a customizable skeleton while the flow is being fetched, plus `isSubmitting` to drive the button's loading state from async submits
 - **Fully Customizable**: Override any component (form, inputs, ui, step, submitButton, submitButtonWrapper, loadingSkeleton)
 - **Optional Dependencies**: Graceful degradation when optional packages like `react-native-document-picker` aren't installed
 - **Theme Support**: Dark/light mode out of the box
@@ -266,7 +267,7 @@ You can customize the appearance using the `style` and `contentContainerStyle` p
 Override default components with your own React Native components.
-Each input renderer receives **two arguments**:
+Each input renderer is a **React component** receiving a single props object with two keys:
 1. `field` — DOM-safe props (`id`, `name`, `value`, `placeholder`, `required`, `aria-invalid`). On the web you can spread them onto an element (`<input {...field} />`); on React Native pick the ones you need.
 2. `extra` — Treege-specific props: `setValue`, `error`, `label`, `helperText`, `node`, and `missingDependencies` (the unfilled fields this input's dynamic options depend on).
@@ -275,7 +276,7 @@ Each input renderer receives **two arguments**:
 import { Text, TextInput, View } from "react-native";
 import { TreegeRenderer } from "treege/renderer-native";
-const CustomTextInput = (field, extra) => {
+const CustomTextInput = ({ field, extra }) => {
   return (
     <View style={{ marginBottom: 16 }}>
       <Text style={{ fontSize: 14, marginBottom: 4 }}>{extra.label}</Text>
@@ -335,22 +336,24 @@ You can implement these inputs using popular React Native libraries:
 The React Native renderer shares the same API as the web renderer, with some platform-specific props:
-| Prop                    | Type                                        | Default      | Description                                                                    |
-|-------------------------|---------------------------------------------|--------------|--------------------------------------------------------------------------------|
-| `flow`                  | `Flow \| null`                              | -            | Decision tree to render                                                        |
-| `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                                                      |
-| `headers`               | `HttpHeaders`                               | -            | HTTP headers as `{ name: value }`, applied to every request (field-level wins) |
-| `isLoading`             | `boolean`                                   | `false`      | Render a loading skeleton instead of the form                                  |
-| `style`                 | `ViewStyle`                                 | -            | ScrollView style (RN only)                                                     |
-| `contentContainerStyle` | `ViewStyle`                                 | -            | Content container style (RN)                                                   |
+| Prop                    | Type                                        | Default      | Description                                                                                                     |
+|-------------------------|---------------------------------------------|--------------|-----------------------------------------------------------------------------------------------------------------|
+| `flow`                  | `Flow \| null`                              | -            | Decision tree to render                                                                                         |
+| `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`                                | `{}`         | Pre-fill values to edit a record. Accepts `node.id` or name keys; reactive (re-seeds if it changes after mount) |
+| `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                                                                                       |
+| `headers`               | `HttpHeaders`                               | -            | HTTP headers as `{ name: value }`, applied to every request (field-level wins)                                  |
+| `isLoading`             | `boolean`                                   | `false`      | Render a loading skeleton instead of the form                                                                   |
+| `isSubmitting`          | `boolean`                                   | `false`      | Force the submit/continue button into its loading state (OR-ed with internal state)                             |
+| `onBack`                | `() => void`                                | -            | Called when Back is clicked on the first step; bridges to an outer flow                                         |
+| `style`                 | `ViewStyle`                                 | -            | ScrollView style (RN only)                                                                                      |
+| `contentContainerStyle` | `ViewStyle`                                 | -            | Content container style (RN)                                                                                    |
 ## Node Types
@@ -452,14 +455,15 @@ Treege supports multiple languages out of the box:
 ### Custom Input Components
-Override default input renderers with your own. A renderer receives two
-arguments: `field` (DOM-safe props, spreadable onto an element) and `extra`
-(`setValue`, `error`, `label`, `helperText`, `node`, `missingDependencies`).
+Override default input renderers with your own. A renderer is a React component
+receiving a single props object: `field` (DOM-safe props, spreadable onto an
+element) and `extra` (`setValue`, `error`, `label`, `helperText`, `node`,
+`missingDependencies`).
 ```tsx
 import { TreegeRenderer } from "treege/renderer";
-const CustomTextInput = (field, extra) => {
+const CustomTextInput = ({ field, extra }) => {
   return (
     <label>
       {extra.label}
@@ -586,6 +590,32 @@ Customize the skeleton via `components.loadingSkeleton`:
 />
 ```
+### Editing an Existing Submission
+To edit a record that was already filled in, pass it to `initialValues`. The keys can be either `node.id` **or** the same name-based keys you receive from `onSubmit`/`onChange`, so you can round-trip the submitted object directly — no remapping needed:
+```tsx
+const handleSubmit = (values) => save(values); // e.g. { firstName: "Alice", email: "a@b.com" }
+// later, to edit the saved record:
+<TreegeRenderer flow={flow} initialValues={savedRecord} onSubmit={handleSubmit} />
+```
+`initialValues` is **reactive**: if it changes after mount (e.g. an async-fetched record resolves later), the form is re-seeded automatically — no `key` prop or `isLoading` gate required. Passing a new object of identical content does not reset the form, so in-progress edits are preserved.
+```tsx
+const { data } = useQuery(/* ... */);
+<TreegeRenderer flow={flow} initialValues={data ?? {}} onSubmit={handleSubmit} />
+```
+### Submitting State
+Pass `isSubmitting` to keep the submit/continue button in its loading state (spinner + disabled) while an async `onSubmit` resolves on your side. It's OR-ed with the renderer's own internal submitting state (e.g. during an HTTP `submitConfig` call):
+```tsx
+<TreegeRenderer flow={flow} isSubmitting={mutation.isPending} onSubmit={handleSubmit} />
+```
 ### Multi-Step Forms
 When a flow contains **Group** nodes, the renderer automatically splits the form into navigable steps — each contiguous slice of visible nodes sharing the same group becomes one step, with built-in Back/Continue controls (Continue turns into Submit on the last step). Branching via conditional edges recomputes the steps on the fly.
@@ -596,13 +626,13 @@ Override the default step layout via `components.step`:
 <TreegeRenderer
   flow={flow}
   components={{
-    step: ({ label, children, isFirstStep, isLastStep, canContinue, onBack, onContinue }) => (
+    step: ({ label, children, canGoBack, isLastStep, canContinue, isSubmitting, onBack, onContinue }) => (
       <section>
         <h2>{label}</h2>
         {children}
-        {!isFirstStep && <button onClick={onBack}>Back</button>}
-        <button disabled={!canContinue} onClick={onContinue}>
-          {isLastStep ? "Submit" : "Continue"}
+        {canGoBack && <button onClick={onBack}>Back</button>}
+        <button disabled={!canContinue || isSubmitting} onClick={onContinue}>
+          {isSubmitting ? "Submitting…" : isLastStep ? "Submit" : "Continue"}
         </button>
       </section>
     ),
@@ -610,6 +640,25 @@ Override the default step layout via `components.step`:
 />
 ```
+Use **`canGoBack`** (not `!isFirstStep`) to decide whether to show the Back control: it's `true` on any step past the first, and also on the first step when an `onBack` prop is provided.
+#### Bridging navigation to an outer flow
+When the renderer is embedded in a surrounding wizard (e.g. a modal with its own steps), use `onBack` to step back out of the renderer's first step, and `formId` to drive submission from an external button:
+```tsx
+<TreegeRenderer
+  flow={flow}
+  formId="treege-form"
+  onBack={() => modal.goToPreviousStep()} // Back on step 0 → previous modal step
+  onSubmit={handleSubmit}
+/>
+// A submit button living outside the renderer (web): only submits on the last
+// step — on earlier steps it advances, like the built-in Continue button.
+<button type="submit" form="treege-form">Save</button>
+```
 ### Headless / Programmatic Control
 Use the `useTreegeRenderer` hook to drive the form yourself (headless mode). It takes the same configuration as `TreegeRenderer` and returns the full form state and control methods:
@@ -701,21 +750,24 @@ Once the development server is running, you can access these examples:
 ### TreegeRenderer Props
-| Prop             | Type                                        | Default      | Description                                                                    |
-|------------------|---------------------------------------------|--------------|--------------------------------------------------------------------------------|
-| `flow`           | `Flow \| null`                              | -            | Decision tree to render                                                        |
-| `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                                                      |
-| `headers`        | `HttpHeaders`                               | -            | HTTP headers as `{ name: value }`, applied to every request (field-level wins) |
-| `isLoading`      | `boolean`                                   | `false`      | Render a loading skeleton instead of the form (see below)                      |
-| `className`      | `string`                                    | -            | Additional CSS class names for custom styling                                  |
+| Prop             | Type                                        | Default      | Description                                                                                                                                                               |
+|------------------|---------------------------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `flow`           | `Flow \| null`                              | -            | Decision tree to render                                                                                                                                                   |
+| `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`                                | `{}`         | Pre-fill values to edit a submitted record. Accepts `node.id` **or** name keys (same shape as `onSubmit`); reactive — re-seeds if it changes after mount (see below)      |
+| `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                                                                                                                                                 |
+| `headers`        | `HttpHeaders`                               | -            | HTTP headers as `{ name: value }`, applied to every request (field-level wins)                                                                                            |
+| `isLoading`      | `boolean`                                   | `false`      | Render a loading skeleton instead of the form (see below)                                                                                                                 |
+| `isSubmitting`   | `boolean`                                   | `false`      | Force the submit/continue button into its loading state (spinner + disabled). OR-ed with the internal submitting state — useful with an async `onSubmit`                  |
+| `onBack`         | `() => void`                                | -            | Called when Back is clicked on the **first step**; bridges back-navigation to an outer flow (e.g. a parent modal). Shows a Back button on step 0 when provided            |
+| `formId`         | `string`                                    | -            | Sets the `<form>` `id` so a submit button outside the renderer can target it via the native `form` attribute. Web only; submits only on the last step in multi-step flows |
+| `className`      | `string`                                    | -            | Additional CSS class names for custom styling                                                                                                                             |
 ## Development