react-formule 1.4.0 → 1.6.0

package/README.md

@@ -70,10 +70,10 @@ Formule includes a variety of predefined field types, grouped in three categorie
 - **Collections**:
   - `Object`: Use it of you want to group fields or to add several of them inside of a `List`.
   - `List`: It allows you to have as many instances of a field or `Object` as you want.
-  - `Accordion`: When containing a `List`, it works as a `List` with collapsible entries.
-  - `Layer`: When containing a `List`, it works as a `List` whose entries will open in a dialog window.
+  - `Accordion`: It works as a `List` with collapsible entries.
+  - `Layer`: It works as a `List` whose entries will open in a dialog window.
   - `Tab`: It's commonly supposed to be used as a wrapper around the rest of the elements. You will normally want to add an `Object` inside and you can use it to separate the form in different pages or sections.
-- **Advanced fields**: More complex or situational fields such as `URI`, `Rich/Latex editor`, `Tags`, `ID Fetcher` and `Code Editor`.
+- **Advanced fields**: More complex or situational fields such as `URI`, `Rich/Latex editor`, `Tags`, `ID Fetcher`, `Code Editor` and `Files`.
 
 You can freely remove some of these predefined fields and add your own custom fields and widgets following the JSON Schema specifications. More details below.
 
@@ -110,27 +110,39 @@ return (
 
 ### Customizing and adding new field types
 
-Override (if existing) or create your own field types (rjsf type definitions) similarly to how it's done in `fieldTypes.jsx`, passing them as `customFieldTypes`. Implement your own custom fields and widgets (react components) by passing them as `customFields` and/or `customWidgets` (see `forms/fields/` and `forms/widgets/` for examples). If you also want to use a different published version of a field or widget, pass the component in `customPublishedFields` or `customPublishedWidgets`.
+Override (if existing) or create your own field types (rjsf type definitions) similarly to how it's done in `fieldTypes.jsx`, passing them as `customFieldTypes`. Implement your own custom fields and widgets (react components) by passing them as `customFields` and/or `customWidgets` (see `forms/fields/` and `forms/widgets/` for examples). If you also want to use a different published version of a field or widget, pass the component in `customPublishedFields` or `customPublishedWidgets`. You can read more about the difference between fields and widgets and how to customize or wrap them in the [rjsf docs](https://rjsf-team.github.io/react-jsonschema-form/docs/advanced-customization/custom-widgets-fields), but make sure you provide Formule with something like the following:
 
 ```jsx
+const CustomWidget = ({value, required, onChange}) => {
+  return (
+    <input
+      type='text'
+      className='custom'
+      value={value}
+      required={required}
+      onChange={(event) => onChange(event.target.value)}
+    />
+  );
+};
+
 const customFieldTypes = {
   advanced: {
-    myfield: {
+    myCustomWidget: {
       title: ...
       ...
     }
   }
 }
 
-const customFields: {
-  myfield: MyField  // react component
+const customWidgets: {
+  myCustomWidget: CustomWidget
 }
 
 <FormuleContext
   theme={{token: {colorPrimary: "blue"}}} // antd theme
   customFieldTypes={customFieldTypes}
-  customFields={customFields}
-  customWidgets={...}
+  customFields={...}
+  customWidgets={customWidgets}
   customPublishedFields={...}
   customPublishedWidgets={...}>
 // ...
@@ -176,9 +188,221 @@ const handleFormuleStateChange = (newState) => {
 
 Alternatively, you can pull the current state on demand by calling `getFormuleState` at any moment.
 
-> [!TIP]
-> For more examples, feel free to browse around formule-demo and the [CERN Analysis Preservation](https://github.com/cernanalysispreservation/analysispreservation.cern.ch) repository, where we use all the features mentioned above.
+### Loading form data / prefill form
+
+If you want to prefill the form with existing data, you can provide the form data to `FormuleForm`. This will fill in the corresponding fields with the information in `formData`:
+
+```jsx
+<FormuleForm
+  formData={{
+    name: "Mule",
+    age: 20,
+    weight: 370,
+  }}
+/>
+```
+
+### Using the Files field
+
+In order to keep Formule's philosophy of storing forms and completion data as simple JSON objects, Formule doesn't directly store files. Instead, it stores only UIDs and leaves the specifics of how, where and when to store the corresponding files up to the user.
+
+<details>
+<summary>More info about <b>fetching and storing files</b> with examples</summary>
+
+#### Fetching files
+
+In order to fetch files from a URL (which can be your backend or a public URL), you will have to provide a `fetchFile` callback function in `customFunctions`. Formule will call this function when first loading a Files field for each of the file UIDs associated to this field, passing the file UID. This function should return a file URL.
+
+```jsx
+<FormuleContext
+  customFunctions={{
+    file: {
+      // You can either directly return the file URL (useful also if you want
+      // to do some kind of caching):
+      fetchFile: (uid) => {
+        return `https://example.com/files/${uid}`;
+      },
+      // Or, if you need to manage e.g. authentication, you can always fetch
+      // the image yourself, doing any processing you find necessary and finally
+      // create an object URL with URL.createObjectURL() and return it:
+      fetchFile: (uid) => {
+        return fetch(`https://example.com/files/${uid}`)
+          .then((response) => response.blob())
+          .then((blob) => URL.createObjectURL(blob));
+      },
+    },
+  }}
+>
+  // ...
+</FormuleContext>
+```
+
+#### Storing files
+
+Formule temporarily stores object URLs of files uploaded in the current session in the Formule state under `files.new`. If you want to persist files you can simply monitor the formule state (see [Syncing Formule state](#syncing-formule-state)) and whenever you want to save them (usually you will want to do it on submission, but you could do it on change) you can read new files from `files.new` and deleted files from `files.deleted`. You can then use that data to trigger the corresponding upload and delete actions in your backend.
+
+```jsx
+// Example of a custom function to handle form submission
+// Only showing file-related logic
+// Assumes you have synchronized the formule state on formuleState
+const handleSubmit = () => {
+  // Upload new files
+  formuleState.files.new.map({uid, url} => {
+    const response = await fetch(url);
+    const blob = await response.blob();
+
+    const formData = new FormData();
+    formData.append('file', blob);
+    formData.append('uid', uid);
+
+    const uploadResponse = await fetch('https://example.com/upload', {
+      method: 'POST',
+      body: formData,
+    });
+    // handle response...
+  })
+
+  // Remove deleted files. You only need to handle this for form edition
+  // (forms already filled-in and saved that are being further modified)
+  // unless you are persisting files on change instead of on submission.
+  formuleState.files.deleted.map(uid => {
+    const response = await fetch(`https://example.com/files/${uid}`, {
+      method: 'DELETE',
+    });
+    // handle response...
+  });
+};
+```
+
+</details>
+
+## ✨ FormuleAI
+
+FormuleAI brings Artificial Intelligence capabilities to Formule, allowing users to **generate and modify form schemas using natural language** prompts. This feature leverages Large Language Models to understand user requirements and automatically create or update form structures.
+
+### How it works
+
+FormuleAI integrates AI providers (like OpenAI or Gemini) to process natural language requests and generate corresponding JSON schemas. The AI understands the current form context and can add new fields, modify existing ones, or restructure entire sections based on your prompts.
+
+By default FormuleAI includes providers for **OpenAI** and **Gemini**, and has been tested to work particularly with `GPT 4.1 Mini` and `Gemini 2.0 Flash`, although it allows you to choose any other model offered by these providers. You can also provide your own API key.
+
+Once you send a request and receive a response back from the LLM, a popover will be displayed showing the diff between the current form and the suggestion, as well as between both JSON schemas, and you will be able to either reject or approve the changes. In the FormuleAI settings, you can also activate the "Vibe Mode", which will auto-apply any change without showing you a diff and asking for approval (use at your own risk).
+
+**Note:** For the moment FormuleAI doesn't keep conversation history, so make sure to always be clear and provide all necessary details in each request.
+
+### Basic usage
+
+The main component you will need to use is **`AiChatFooter`**, a chat interface where users can input their prompts, toggle diffs, and accept or reject changes. It will also allow you to configure some settings and provide some usage instructions.
+
+It can receive the following props: `onApply` and `onReject` callbacks, `hideHelp` and `hideSettings`, and `vibeMode` (false to disable, true to enable, unset to leave the decision up to users via settings).
+
+A basic configuration would be simply:
+
+```jsx
+import { FormuleContext, AiChatFooter } from "react-formule";
+
+<FormuleContext>
+  // your other main formule components
+  <AiChatFooter />
+</FormuleContext>;
+```
+
+<details>
+<summary>Adding <b>custom providers</b> and advanced configuration</summary>
+
+### Customizing AI providers
+
+You can add a new provider, whether commercial or self-hosted, in the following way:
+
+```jsx
+import { defaultProviders } from "react-formule";
+
+const customProviders = {
+  "local-llama": {
+    label: <span>Local llama</span>,
+    // Optional, otherwise users can provide their own via settings
+    apiKey: "your-api-key",
+    // Optional, otherwise users can select one via settings (you need to define fetchModels for that)
+    model: "llama3.1",
+    // Optional (not needed when providing a model), it preselects that model in the model list
+    recommendedModel: { id: "llama3.1", name: "LLaMA 3.1" }
+    // Optional, needed only if you don't provide a model
+    fetchModels: async (apiKey) => {
+      const response = await fetch("https://your-ai-endpoint/models", {
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+      const data = await response.json();
+      return data.models.map((model) => ({
+        id: model.id,
+        name: model.display_name,
+      }));
+    },
+    generateSchema: async (
+      prompt,
+      currentSchema,
+      fieldTypes,
+      apiKey,
+      model
+    ) => {
+      const response = await fetch("https://your-ai-endpoint", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({
+          model: model,
+          messages: [
+            {
+              role: "system",
+              content: "<your system prompt>",
+            },
+            {
+              role: "user",
+              content: "<your user prompt including fieldTpes and currentSchema>"
+            }
+          ],
+          response_format: { type: "json_object" }
+        }),
+      });
+      return {
+        schema: content.schema,
+        uiSchema: content.uiSchema,
+        usage,  // Optionally you can include token usage stats to be displayed to users
+      };
+      // If error, `return { error: "the error message" }` instead
+    },
+  },
+};
+
+<FormuleContext ai={{ providers: { ...defaultProviders, ...customProviders } }}>
+  // ...
+</FormuleContext>;
+```
+
+If you want to keep the default providers along with your custom ones, you can import `defaultProviders` and include it in your providers object (as you can see in the previous example). Otherwise your new providers will override that configuration.
+
+If an API key or a model is defined in a provider, users will not be able to modify them in the settings for that provider.
+
+### Utility functions, hooks and components
+
+FormuleAI exports several utilities for advanced use cases:
+
+- **`useGenerateSchema`**: Hook for triggering schema generation programmatically
+- **`useGetProvider`**: Hook to access configured AI providers. It will return the provider selected by the user (from localStorage) or otherwise a valid provider which is fully configured (with API key and model) in `ai.providers` if any.
+- **`generatePatches`**: Utility to create JSON patches between schemas, used by FormuleAI for the form diff.
+- **`defaultProviders`**: Configuration of the default providers, mentioned in the examples above.
+- **`defaultGenerationPrompt`**: The default system prompt used by the current providers. It can help as a starting point to experiment with custom providers, but you will likely have to do some adjustments for each one.
+
+There are also two more components that you would normally not need to use explicitly (they are already used by default from `AiChatFooter`) but which are still exposed to give you more flexiility in case you want further customization or to use them on your own custom chat interface implementation:
+
+- **`AiDiff`**: Shows a visual diff of proposed changes before applying them
+- **`AiSettingsDialog`**: Configuration panel for API keys and model selection
+
+For implementation examples and advanced configurations, refer to the default provider implementations in the codebase.
+
+</details>
 
 ## :space_invader: Local demo & how to contribute
 
 Apart from trying the online [demo](https://cern-sis.github.io/react-formule/) you can clone the repo and run `formule-demo` to play around. Follow the instructions in its [README](./formule-demo/README.md): it will explain how to install `react-formule` as a local dependency so that you can modify Formule and test the changes live in your host app, which will be ideal if you want to troubleshoot or contribute to the project. Your contributions are welcome! :rocket:
+
+> [!TIP]
+> For more examples, feel free to browse around formule-demo and the [CERN Analysis Preservation](https://github.com/cernanalysispreservation/analysispreservation.cern.ch) repository, where we use most of the features mentioned above.

package/dist/admin/formComponents/PropKeyEditorObjectFieldTemplate.d.ts

@@ -0,0 +1,4 @@
+export default PropKeyEditorObjectFieldTemplate;
+declare function PropKeyEditorObjectFieldTemplate({ properties }: {
+    properties: any;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/admin/formComponents/SortableBox.d.ts

@@ -1,18 +1,16 @@
-import { default as PropTypes } from 'prop-types';
-export default SortableBox;
-declare function SortableBox({ parent, children, id, index, moveCard }: {
-    parent: any;
-    children: any;
-    id: any;
-    index: any;
-    moveCard: any;
-}): import("react/jsx-runtime").JSX.Element;
-declare namespace SortableBox {
-    namespace propTypes {
-        let parent: PropTypes.Requireable<string>;
-        let children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
-        let id: PropTypes.Requireable<number>;
-        let index: PropTypes.Requireable<number>;
-        let moveCard: PropTypes.Requireable<(...args: any[]) => any>;
-    }
+import { ReactNode } from 'react';
+
+interface SortableBoxProps {
+    children: ReactNode;
+    parent: string;
+    id: number;
+    index: number;
+    onDragStart: () => void;
+    onDragEnd: () => void;
+    onDragCancel: () => void;
+    updateVisualOrder: (dragIndex: number, hoverIndex: number) => void;
+    moveItem: () => void;
 }
+declare function SortableBox({ children, parent, id, index, onDragStart, onDragEnd, onDragCancel, moveItem, updateVisualOrder, }: SortableBoxProps): import("react/jsx-runtime").JSX.Element;
+declare const _default: import('react').MemoExoticComponent<typeof SortableBox>;
+export default _default;