@react-fabric/form 1.0.0-beta.5 → 1.0.0-beta.52

package/src/form/Form.tsx

@@ -23,7 +23,7 @@
 
 import { yupResolver } from "@hookform/resolvers/yup";
 import { useDebounce } from "@react-fabric/core";
-import { type yup } from "@react-fabric/utilities";
+import { EMPTY_OBJECT, type yup } from "@react-fabric/utilities";
 import {
   useCallback,
   useEffect,
@@ -40,6 +40,12 @@ import {
   type FormState,
 } from "react-hook-form";
 
+type NestedKeyOf<T extends object> = {
+  [K in keyof T & (string | number)]: T[K] extends object
+    ? `${K}` | `${K}.${NestedKeyOf<T[K]>}`
+    : K;
+}[keyof T & (string | number)];
+
 export interface FormRef<K extends KeyValue> {
   state: FormState<K>;
   reset: () => void;
@@ -47,7 +53,7 @@ export interface FormRef<K extends KeyValue> {
   submit: () => void;
   validate: () => Promise<boolean>;
   getValues: () => K;
-  setValue: (key: keyof K, value: AnyObject) => void;
+  setValue: (key: NestedKeyOf<K>, value: AnyObject) => void;
   setValues: (values: K) => void;
 }
 
@@ -73,11 +79,42 @@ export interface FormProps<K extends KeyValue = KeyValue> {
 
 const DEFAULT_SUBMIT = () => undefined;
 
+/**
+ * Form component for managing form state and validation using react-hook-form and yup.
+ * It provides a simple interface for form handling, including submission, validation, and value management.
+ * It supports nested form structures and allows for custom validation schemas using Yup.
+ *
+ * @param {FormProps<K>} props - The properties for the Form component.
+ * @returns {JSX.Element} The rendered Form component.
+ *
+ * @example
+ * ```jsx
+ * <Form
+ *   formRef={formRef}
+ *   schema={yup.object().shape({
+ *     name: yup.string().required("Name is required"),
+ *     email: yup.string().email("Invalid email").required("Email is required"),
+ *   })}
+ *   defaultValues={{ name: "", email: "" }}
+ *   onSubmit={(values) => {
+ *     console.log("Form submitted with values:", values);
+ *   }}
+ * >
+ *   <input name="name" ref={form.register} placeholder="Name" />
+ *   <input name="email" ref={form.register} placeholder="Email" />
+ *   <button type="submit">Submit</button>
+ * </Form>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/form-form--docs} for the properties that can be passed to this component.
+ * @see {@link https://react-hook-form.com/docs/useform} for more details on the properties.
+ * @see {@link https://github.com/jquense/yup} for more details on the Yup validation schema.
+ */
 export const Form = <K extends KeyValue>({
   formRef,
   schema,
   children,
-  defaultValues,
+  defaultValues = EMPTY_OBJECT as K,
   onSubmit = DEFAULT_SUBMIT,
   onChange,
   ...rest
@@ -90,7 +127,7 @@ export const Form = <K extends KeyValue>({
   });
 
   const [, startTransition] = useTransition();
-  const changeHandler = useDebounce(onChange, [onChange]);
+  const changeHandler = useDebounce(onChange, [onChange], 300);
   useEffect(() => {
     const subscription = form.watch((value) => {
       startTransition(() => changeHandler?.(value as K));
@@ -150,7 +187,10 @@ export const Form = <K extends KeyValue>({
       <form
         ref={ref}
         onReset={() => handleReset(defaultValues)}
-        onSubmit={form.handleSubmit(onSubmit, onInvalid) as AnyObject}
+        onSubmit={(e) => {
+          e.stopPropagation();
+          void form.handleSubmit(onSubmit, onInvalid)(e);
+        }}
         data-loading={form.formState.isSubmitting}
         className="contents"
         autoComplete="off"

package/src/hooks/useFileUploader.ts

@@ -57,6 +57,22 @@ type UploaderActions =
   | { type: "remove"; key: string }
   | { type: "abort"; key: string };
 
+/**
+ * useFileUploader hook provides a way to handle file uploads
+ * with progress tracking, error handling, and file management.
+ * It uses a reducer to manage the state of uploaded files and their statuses.
+ *
+ * @param uploader - The function that handles the file upload.
+ * @param initialList - Initial list of files to be managed by the uploader.
+ * @param multiple - Whether to allow multiple file uploads or not.
+ * @returns An object containing methods to upload, remove, retry files,
+ *          and the current state of the uploader including pending uploads and file list.
+ *
+ * @example
+ * ```jsx
+ * const { upload, remove, retry, state } = useFileUploader(uploader, initialList, multiple);
+ * ```
+ */
 export const useFileUploader = (
   uploader: UploadHandler,
   initialList?: string | FileInfo | FileInfo[],

package/src/hooks/useFormBuilder.tsx

@@ -21,38 +21,47 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+import { EmptyContent } from "@react-fabric/core";
 import { isEmpty, isNil, yup } from "@react-fabric/utilities";
 import { Fragment, useMemo } from "react";
 import { FormField } from "../builder/FormField";
-import { type FormSchema } from "../types/schema";
+import { type BaseSelectProps } from "../types";
+import { DATA_TYPES, type FormSchema, type SchemaDef } from "../types/schema";
 import { type UploadHandler } from "./useFileUploader";
 
-const makeYupField = (field: FormSchema) => {
-  let yupField: AnyObject = yup.string();
-  if (field.datatype === "schema") {
+const makeYupField = (field: SchemaDef) => {
+  let yupField: AnyObject = yup.string().trim();
+  if (field.datatype === DATA_TYPES.SCHEMA) {
     const child: yup.ObjectShape = Object.fromEntries(
       field.schema.map((field) => [field.id, makeYupField(field)]),
     );
     yupField = yup.object(child);
   }
-  if (field.datatype === "boolean") yupField = yup.boolean();
+  if (field.datatype === DATA_TYPES.BOOL) {
+    yupField = yup.boolean();
+    if (field.required)
+      yupField = yupField.test({
+        test: (value: boolean) => !!value,
+      });
+  }
   if (
-    field.datatype === "decimal" ||
-    field.datatype === "number" ||
-    field.datatype === "range"
+    field.datatype === DATA_TYPES.NUMBER ||
+    field.datatype === DATA_TYPES.RANGE
   ) {
     yupField = yup.number();
     !isNil(field.min) && (yupField = yupField.min(field.min));
     !isNil(field.max) && (yupField = yupField.max(field.max));
 
-    if (field.datatype === "range") yupField = yup.array(yupField);
+    if (field.datatype === DATA_TYPES.RANGE) yupField = yup.array(yupField);
   }
-  if (field.datatype === "string") {
-    field.options && (yupField = yupField.oneOf(field.options));
+  if (field.datatype === DATA_TYPES.STRING) {
+    field.options &&
+      !field.allowCustom &&
+      (yupField = yupField.oneOf(field.options));
     field.regex && (yupField = yupField.matches(new RegExp(field.regex)));
   }
 
-  if (field.datatype === "file") {
+  if (field.datatype === DATA_TYPES.FILE) {
     yupField = yup
       .object({
         filename: yup.string().required(),
@@ -83,13 +92,43 @@ const makeYupField = (field: FormSchema) => {
   return yupField.label(field.label);
 };
 
-export const useFormBuilder = (
-  schema: FormSchema[],
+/**
+ * useFormBuilder hook to create a form definition based on a schema.
+ * It generates a Yup validation schema and a form definition component.
+ *
+ * @param {FormSchema} schema - The schema defining the form fields.
+ * @param {Object} options - Optional parameters for the form builder.
+ * @returns An object containing the form definition and the Yup validation schema.
+ *
+ * @example
+ * ```jsx
+ * const { formDef, schemaDef } = useFormBuilder(schema, {
+ *   prefix: "form",
+ *   inline: true,
+ *   fileUrl: (path) => `/files/${path}`,
+ *   uploadHandler: async (file) => {
+ *    // handle file upload
+ *   },
+ *  optionLists: {
+ *    // define option lists for select fields
+ *  }
+ * * });
+ * <FormBuilder
+ *   schema={schemaDef}
+ *   onSubmit={(data) => console.log(data)}
+ * >
+ *   {formDef}
+ * </FormBuilder>
+ * ```
+ */
+export const useFormBuilder = <T extends AnyObject = string>(
+  schema: FormSchema,
   options: {
     prefix?: string;
     inline?: boolean;
     fileUrl?: (path: string) => string;
     uploadHandler?: UploadHandler;
+    optionLists?: KeyValue<BaseSelectProps<T>>;
   } = {},
 ) => {
   const filteredSchema = useMemo(
@@ -106,11 +145,12 @@ export const useFormBuilder = (
     <Fragment>
       {filteredSchema.map((field, idx) => (
         <div className="mb-4" key={field.id}>
-          {field.datatype === "schema" ? null : (
+          {field.datatype === DATA_TYPES.SCHEMA ? null : (
             <FormField
               {...field}
               autoFocus={idx === 0}
               fileUrl={options.fileUrl}
+              optionLists={options.optionLists}
               uploadHandler={options.uploadHandler}
               inline={options.inline}
               prefix={options.prefix}
@@ -118,6 +158,9 @@ export const useFormBuilder = (
           )}
         </div>
       ))}
+      {filteredSchema.length === 0 && (
+        <EmptyContent message="No schema defined" />
+      )}
     </Fragment>
   );
 

package/src/i18n/ar.json

@@ -1,17 +1,18 @@
 {
   "addArray": "اضافة عنصر",
   "password": {
-    "show": "عرض كلمة المرور",
-    "hide": "اخفاء كلمة المرور"
+    "hide": "اخفاء كلمة المرور",
+    "show": "عرض كلمة المرور"
   },
   "select": {
+    "createOption": "إنشاء خيار جديد ل ",
     "emptyList": "لا توجد خيارات متاحة",
-    "notFound": "لم يتم العثور على خيارات ل ",
-    "createOption": "إنشاء خيار جديد ل "
+    "notFound": "لم يتم العثور على خيارات ل "
   },
   "yup": {
     "arrayMax": "{{label}} حدد ما يصل {{max}} غرض",
     "arrayMin": "{{label}} اختر على الأقل {{min}} غرض",
+    "empty": "{{label}} يجب ألا يكون فارغًا",
     "invalid": "{{label}} نوع بيانات غير صالح",
     "invalidType": "{{label}} غير صالح",
     "numberMax": "{{label}} الحد الأقصى {{max}}",

package/src/i18n/en.json

@@ -1,19 +1,19 @@
 {
   "addArray": "Add Item",
   "password": {
-    "show": "Show password",
-    "hide": "Hide password"
+    "hide": "Hide password",
+    "show": "Show password"
   },
   "select": {
+    "createOption": "Create new option for <0>{{query}}</0>",
     "emptyList": "No options available",
-    "notFound": "No options found for <0>{{query}}</0>",
-    "createOption": "Create new option for <0>{{query}}</0>"
+    "notFound": "No options found for <0>{{query}}</0>"
   },
   "yup": {
     "arrayMax": "{{label}} must contain upto {{max}} item",
     "arrayMin": "{{label}} must contain atleast {{min}} item",
-    "invalid": "{{label}} invalid",
     "empty": "{{label}} must not be empty",
+    "invalid": "{{label}} invalid",
     "invalidType": "{{label}} invalid datatype",
     "numberMax": "{{label}} maximum {{max}}",
     "numberMin": "{{label}} minimum {{min}}",

package/src/index.ts

@@ -26,15 +26,24 @@ import "./i18n";
 export { Controller } from "./form/Controller";
 export { Form, type FormRef } from "./form/Form";
 
+export { SchemaEditor } from "./builder/SchemaEditor";
+
 export { useFileUploader } from "./hooks/useFileUploader";
 export { useFormBuilder } from "./hooks/useFormBuilder";
 
-export { type FormSchema } from "./types/schema";
+export {
+  DATA_TYPES,
+  SCHEMA_CUSTOM_LIST,
+  type FormSchema,
+  type SchemaDef,
+} from "./types/schema";
 
 export { ArrayInput } from "./input/ArrayInput";
+export { AvatarInput } from "./input/AvatarInput";
 export { Checkbox } from "./input/Checkbox";
 export { ColorInput } from "./input/ColorInput";
 export { ColorPicker } from "./input/ColorPicker";
+export { DateInput } from "./input/DateInput";
 export { Field } from "./input/Field";
 export { FileInput } from "./input/File";
 export { HiddenInput } from "./input/Hidden";
@@ -43,7 +52,7 @@ export { Number } from "./input/Number";
 export { Password } from "./input/Password";
 export { Radio } from "./input/Radio";
 export { RadioGroup } from "./input/RadioGroup";
-export { Range } from "./input/Range";
+export { RangeSlider } from "./input/RangeSlider";
 export { Search } from "./input/Search";
 export { Slider } from "./input/Slider";
 export { Switch } from "./input/Switch";

package/src/input/ArrayInput.tsx

@@ -23,27 +23,32 @@
 
 import { DndContext, type DragEndEvent } from "@dnd-kit/core";
 import { SortableContext, useSortable } from "@dnd-kit/sortable";
-import { Button, CoreIcons, Icon, Tooltip } from "@react-fabric/core";
-import { isString } from "@react-fabric/utilities";
+import {
+  Button,
+  cloneChildren,
+  CoreIcons,
+  Icon,
+  Tooltip,
+} from "@react-fabric/core";
+import { isFalse, isString } from "@react-fabric/utilities";
 import classNames from "classnames";
 import {
-  Children,
   cloneElement,
   useCallback,
   useImperativeHandle,
   useMemo,
   type PropsWithChildren,
   type ReactNode,
-  type RefObject,
+  type Ref,
 } from "react";
 import { useFieldArray, useFormContext } from "react-hook-form";
 import { useTranslation } from "react-i18next";
 import { FieldWrapper } from "../internal/FieldWrapper";
-import classes from "./ArrayInput.module.css";
 
 import { restrictToVerticalAxis } from "@dnd-kit/modifiers";
 import { CSS } from "@dnd-kit/utilities";
-export interface ArrayInputProps {
+
+export interface ArrayInputProps<T extends AnyObject = string> {
   /**
    * input label
    */
@@ -77,6 +82,10 @@ export interface ArrayInputProps {
    * minimum required length
    */
   minItems?: number;
+  /**
+   * maximum length
+   */
+  maxItems?: number;
   /**
    * field name to focus on add
    */
@@ -92,34 +101,104 @@ export interface ArrayInputProps {
    * add item button label
    */
   addLabel?: string;
+  buttonPosition?: "top" | "bottom" | "both";
   /**
    * fixed length list
    */
   fixedList?: boolean;
-  arrayRef?: RefObject<{
-    addItem: (item: AnyObject) => void;
+  arrayRef?: Ref<{
+    addItem: (item: T) => void;
     removeItem: (idx: number) => void;
   }>;
   /**
-   * Add item
+   * add new item
    */
   onAdd?: () => AnyObject;
+  /**
+   * on item remove
+   */
+  onRemove?: (item: T, idx: number) => void;
+  /**
+   * before item remove
+   */
+  onBeforeRemove?: (item: T, idx: number) => Promise<boolean> | boolean;
+  /**
+   * can remove item
+   */
+  canRemove?: (props: { item: T; index: number; lastItem: boolean }) => boolean;
+
+  /**
+   * field width
+   */
+  width?: number | string;
+  /**
+   * inline label and input
+   */
+  inline?: boolean;
+  /**
+   * label width for inline
+   */
+  labelWidth?: string;
 }
 
-export const ArrayInput = ({
+/**
+ * ArrayInput component for managing an array of items in a form.
+ * It allows adding, removing, and sorting items within the array.
+ * It integrates with react-hook-form for form state management and validation.
+ * It supports fixed-length lists, custom add/remove handlers, and can display validation errors.
+ * It also provides options for inline display and custom button positioning.
+ *
+ * It uses the `useFieldArray` hook from `react-hook-form` to manage the array state and provides a simple interface for adding and removing items.
+ *
+ * It also supports drag-and-drop sorting using `@dnd-kit/core` and `@dnd-kit/sortable` for a better user experience when reordering items.
+ *
+ * @param {ArrayInputProps<T>} props - The properties for the ArrayInput component.
+ * @returns {JSX.Element} The rendered ArrayInput component.
+ *
+ * @example
+ * ```jsx
+ * <ArrayInput
+ *   name="items"
+ *   label="Items"
+ *   addLabel="Add Item"
+ *   onAdd={() => ({ name: "", value: "" })}
+ *   onRemove={(item, index) => console.log("Removed item:", item, "at index:", index)}
+ *   onBeforeRemove={(item, index) => confirm(`Are you sure you want to remove item at index ${index}?`)}
+ *   canRemove={({ item, index, lastItem }) => !lastItem} // Prevent removing the last item
+ * >
+ *   {({ index, name }) => (
+ *     <Input
+ *       name={name}
+ *       label={`Item ${index + 1}`}
+ *       placeholder="Enter item value"
+ *       required={index === 0} // Make the first item required
+ *     />
+ *   )}
+ * </ArrayInput>
+ * ```
+ *
+ * @see {@link https://react-hook-form.com/api/usefieldarray} for more details on `useFieldArray`.
+ * @see {@link https://react-dnd.github.io/react-dnd/about} for more details on DnD context and sorting.
+ */
+export const ArrayInput = <T extends AnyObject = string>({
   name,
   children,
   addLabel,
   fixedList,
   focusName = "",
+  buttonPosition = "bottom",
   onAdd,
+  onRemove,
+  onBeforeRemove,
+  canRemove,
   arrayRef,
   enableSorting,
   disabled = false,
   readOnly = false,
   minItems = 0,
+  maxItems = Number.MAX_SAFE_INTEGER,
   ...rest
-}: ArrayInputProps) => {
+}: ArrayInputProps<T>) => {
   const { t } = useTranslation("form");
   const form = useFormContext();
 
@@ -128,6 +207,7 @@ export const ArrayInput = ({
 
   const { fields, append, remove, move } = useFieldArray({
     name,
+    keyName: "__ID__",
     control: form.control,
   });
 
@@ -139,7 +219,7 @@ export const ArrayInput = ({
   );
 
   const handleAdd = useCallback(
-    (item: AnyObject) => {
+    (item: T) => {
       append(item);
       setTimeout(() => {
         form.setFocus(
@@ -150,6 +230,19 @@ export const ArrayInput = ({
     [name, fields, focusName],
   );
 
+  const handleRemove = useCallback(
+    (item: T, index: number) => {
+      const ret = onBeforeRemove?.(item, index);
+      void Promise.resolve(ret).then((b) => {
+        if (!isFalse(b)) {
+          remove(index);
+          onRemove?.(item, index);
+        }
+      });
+    },
+    [remove, onRemove, onBeforeRemove],
+  );
+
   useImperativeHandle(arrayRef, () => ({
     addItem: handleAdd,
     removeItem: remove,
@@ -159,7 +252,7 @@ export const ArrayInput = ({
     ({ children }: PropsWithChildren) => {
       if (enableSorting) {
         // pass id list to dnd context
-        const idMap = fields.map((item) => item.id);
+        const idMap = fields.map((item) => item.__ID__);
         const handleDragEnd = (e: DragEndEvent) => {
           if (e.over && e.active.id !== e.over.id) {
             // find index of item and drop over
@@ -227,14 +320,60 @@ export const ArrayInput = ({
   // @ts-expect-error ignore
   SortableItem.displayName = "SortableItem";
 
+  const addButton = useMemo(
+    () => (
+      <div className="flex justify-end">
+        <Tooltip
+          color="danger-200"
+          content={
+            isString(error)
+              ? `${error}`
+              : (t(
+                  error?.key,
+                  error?.values
+                    ? {
+                        ...error?.values,
+                        label: t(
+                          error.values?.label ?? "form:badkey",
+                          error.values?.path,
+                        ),
+                      }
+                    : {},
+                ) as string)
+          }
+        >
+          <Button
+            size="sm"
+            aria-label="Add item"
+            icon={CoreIcons.insert}
+            onClick={() => handleAdd(onAdd?.())}
+            data-invalid={!!error}
+            disabled={!!disabled || readOnly || fields.length > maxItems}
+            className={classNames("fabric-addButton", "me-10")}
+          >
+            {addLabel ?? t("addArray")}
+          </Button>
+        </Tooltip>
+      </div>
+    ),
+    [error, fields, handleAdd, disabled, readOnly, addLabel, maxItems],
+  );
+
   return (
-    <div className={classes.arrayInput}>
-      <FieldWrapper {...rest}>
+    <div className={"fabric-arrayInput"}>
+      <FieldWrapper
+        {...rest}
+        appendLabel={
+          <div className="-me-2">
+            {!fixedList && onAdd && buttonPosition !== "bottom" && addButton}
+          </div>
+        }
+      >
         <Wrapper>
           {fields.map((item, index) => (
             <SortableItem
-              key={item.id}
-              id={item.id}
+              key={item.__ID__}
+              id={item.__ID__}
               className="flex items-center flex-nowrap gap-2 mb-1"
             >
               {typeof children === "function"
@@ -242,7 +381,7 @@ export const ArrayInput = ({
                     index,
                     name: `${name}.${index}`,
                   })
-                : Children.map(children, (child: AnyObject) =>
+                : cloneChildren(children, (child: AnyObject) =>
                     cloneElement(
                       child,
                       Object.assign(
@@ -271,48 +410,24 @@ export const ArrayInput = ({
                   color="danger"
                   variant="link"
                   className="self-end"
-                  disabled={disabled || readOnly || fields.length <= minItems}
-                  onClick={() => remove(index)}
+                  disabled={
+                    disabled ||
+                    readOnly ||
+                    fields.length <= minItems ||
+                    canRemove?.({
+                      item: item as T,
+                      index,
+                      lastItem: index + 1 === fields.length,
+                    }) !== false
+                  }
+                  onClick={() => handleRemove(item as T, index)}
                 />
               )}
             </SortableItem>
           ))}
         </Wrapper>
       </FieldWrapper>
-      {!fixedList && onAdd && (
-        <div className="flex justify-end">
-          <Tooltip
-            color="danger"
-            content={
-              isString(error)
-                ? `${error}`
-                : (t(
-                    error?.key,
-                    error?.values
-                      ? {
-                          ...error?.values,
-                          label: t(
-                            error.values?.label ?? "form:badkey",
-                            error.values?.path,
-                          ),
-                        }
-                      : {},
-                  ) as string)
-            }
-          >
-            <Button
-              aria-label="Add item"
-              icon={CoreIcons.insert}
-              onClick={() => handleAdd(onAdd())}
-              data-invalid={!!error}
-              disabled={!!disabled || readOnly}
-              className={classNames(classes.addButton, "me-10")}
-            >
-              {addLabel ?? t("addArray")}
-            </Button>
-          </Tooltip>
-        </div>
-      )}
+      {!fixedList && onAdd && buttonPosition !== "top" && addButton}
     </div>
   );
 };