react-formule 1.3.0 → 1.5.0

package/README.md

@@ -4,8 +4,6 @@
 
 [![Try our demo](https://img.shields.io/badge/try_our-🕹️_demo_🕹️-deepskyblue.svg?style=for-the-badge)](https://cern-sis.github.io/react-formule/)
 
-</div>
-
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![NPM Version](https://img.shields.io/npm/v/react-formule?style=flat-square&color=orchid)](https://www.npmjs.com/package/react-formule?activeTab=readme)
 [![GitHub commits since tagged version](https://img.shields.io/github/commits-since/cern-sis/react-formule/latest?style=flat-square&color=orange)](https://github.com/cern-sis/react-formule/commits/master/)
@@ -15,6 +13,8 @@
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/cern-sis/react-formule/cypress.yml?style=flat-square&label=cypress)](https://github.com/cern-sis/react-formule/actions/workflows/cypress.yml)
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/cern-sis/react-formule/deploy-demo.yml?style=flat-square&label=deploy-demo)](https://github.com/cern-sis/react-formule/actions/workflows/commit-lint.yml)
 
+</div>
+
 ## :horse: What is Formule?
 
 Formule is a **powerful, user-friendly, extensible and mobile-friendly form building library** based on [JSON Schema](https://json-schema.org/) and [RJSF](https://github.com/rjsf-team/react-jsonschema-form), which aims to make form creation easier for both technical and non-technical people.
@@ -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,6 +188,94 @@ const handleFormuleStateChange = (newState) => {
 
 Alternatively, you can pull the current state on demand by calling `getFormuleState` at any moment.
 
+### 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>
+
 > [!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.
 

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;