@overmap-ai/forms 0.0.1-master.3

package/src/forms/builder/FieldWithActions.tsx

@@ -0,0 +1,129 @@
+import { Draggable } from "@hello-pangea/dnd"
+import { Card, useToast } from "@overmap-ai/blocks"
+import { useFormikContext } from "formik"
+import { ChangeEvent, memo, useCallback, useMemo } from "react"
+
+import { maxFileSizeB } from "../fields/constants"
+import { ISerializedField } from "../typings"
+import { FieldActions } from "./FieldActions"
+import { FieldBuilder, FieldBuilderProps } from "./FieldBuilder"
+import { FormikUserFormRevision, NestedFieldPath } from "./typings"
+import { createNewField, useFieldReordering } from "./utils"
+
+interface FieldWithActionsProps {
+	field: ISerializedField
+	index: number
+	sectionIndex: number
+	remove: () => void
+}
+
+export const FieldWithActions = memo((props: FieldWithActionsProps) => {
+	const { field, index, sectionIndex, remove } = props
+	const { setFieldValue, values } = useFormikContext<FormikUserFormRevision>()
+	const { reorderField } = useFieldReordering()
+	const { showError } = useToast()
+
+	const parentPath: NestedFieldPath = `fields.${sectionIndex}.fields`
+
+	const editFieldProps: FieldBuilderProps = useMemo(
+		() => ({
+			index,
+			parentPath,
+			initial: field,
+		}),
+		[field, index, parentPath],
+	)
+
+	const duplicateField = useCallback(() => {
+		const label = field.label ?? "Unlabelled field"
+		const duplicatedField = {
+			...field,
+			label,
+		}
+
+		createNewField(parentPath, index + 1, duplicatedField, values, setFieldValue)
+	}, [field, parentPath, index, values, setFieldValue])
+
+	const moveField = useCallback(
+		(direction: "up" | "down") => {
+			const srcSectionIndex = sectionIndex
+			const srcSection = values.fields[srcSectionIndex]!
+			let destSectionIndex = sectionIndex
+			let destFieldIndex = direction === "up" ? index - 1 : index + 1
+			if (direction === "up" && index === 0) {
+				destSectionIndex = sectionIndex - 1
+				destFieldIndex = values.fields[destSectionIndex]!.fields.length
+			} else if (direction === "down" && index === srcSection.fields.length - 1) {
+				destSectionIndex = sectionIndex + 1
+				destFieldIndex = 0
+			}
+			const destSection = values.fields[destSectionIndex]
+
+			reorderField(
+				srcSection,
+				srcSectionIndex,
+				index,
+				destSection,
+				destSectionIndex,
+				destFieldIndex,
+				setFieldValue,
+			)
+		},
+		[sectionIndex, values.fields, index, reorderField, setFieldValue],
+	)
+
+	const uploadImage = useCallback(
+		(event: ChangeEvent<HTMLInputElement>) => {
+			const { files } = event.target
+			if (!files || files.length !== 1) return
+
+			const file = files.item(0)
+			if (!file) return
+
+			// Don't add file if it exceeds the maximum file size
+			if (file.size > maxFileSizeB) {
+				showError({
+					title: "File upload error",
+					description: `The file ${file.name} exceeded the maximum file size`,
+				})
+				return
+			}
+			// Set image field but don't upload until form is submitted
+			void setFieldValue(`${parentPath}.${index}`, {
+				...field,
+				image: file,
+			}).then()
+		},
+		[field, index, parentPath, setFieldValue, showError],
+	)
+
+	return (
+		<Draggable draggableId={field.identifier} index={index}>
+			{(draggableProvided) => (
+				<Card
+					ref={draggableProvided.innerRef}
+					{...draggableProvided.draggableProps}
+					{...draggableProvided.dragHandleProps}
+					// using margin bottom instead of flex gap to avoid a bug where the
+					// gap is not applied to dragged elements
+					className="mb-4"
+				>
+					<div className="flex items-center justify-between gap-4 w-full">
+						<FieldBuilder {...editFieldProps} />
+						<FieldActions
+							index={index}
+							type={field.type}
+							sectionIndex={sectionIndex}
+							remove={remove}
+							duplicate={duplicateField}
+							move={moveField}
+							upload={uploadImage}
+						/>
+					</div>
+				</Card>
+			)}
+		</Draggable>
+	)
+})
+
+FieldWithActions.displayName = "FieldWithActions"

package/src/forms/builder/FieldsEditor.tsx

@@ -0,0 +1,180 @@
+import { DragDropContext, Droppable, OnDragEndResponder, OnDragStartResponder } from "@hello-pangea/dnd"
+import { Button, RiIcon } from "@overmap-ai/blocks"
+import { useFormikContext } from "formik"
+import { Fragment, memo, useCallback, useEffect, useReducer } from "react"
+
+import { SerializedFieldSection } from "../typings"
+import { initializer, reducer } from "./DropDispatch"
+import { FieldSectionWithActions } from "./FieldSectionWithActions"
+import { FormikUserFormRevision } from "./typings"
+import { createNewEmptySection, useFieldReordering } from "./utils"
+
+/**
+ * NOTE: Because this returns a new array instance on every call, it will cause re-renders if not destructured.
+ *
+ * BAD:
+ * ```
+const section: [SerializedFieldSection, string] | undefined = findSection(values.fields, source.droppableId)
+const myEffect = useEffect(() => { doSomethingWith(section) }, [section])
+```
+ * GOOD:
+```
+const [section, i]: [SerializedFieldSection, string] | undefined = findSection(values.fields, source.droppableId)
+const myEffect = useEffect(() => { doSomethingWith(section, index) }, [section, i])
+```
+ */
+const findSection = (
+	fields: SerializedFieldSection[],
+	sectionId: string,
+): [SerializedFieldSection, string] | undefined => {
+	for (const [i, section] of Object.entries(fields)) {
+		if (section.identifier === sectionId) return [section, i]
+	}
+}
+
+// TODO: Use the BasicFieldSection component when tackling the auto-scrolling issue that occurs when dragging very tall sections
+// interface BasicFieldSectionProps {
+// 	field: SerializedFieldSection
+// 	provided: DraggableProvided | undefined
+// }
+//
+// const BasicFieldSection = memo((props: BasicFieldSectionProps) => {
+// 	const { field, provided } = props
+// 	return (
+// 		<Card
+// 			ref={provided?.innerRef}
+// 			{...provided?.draggableProps}
+// 			{...provided?.dragHandleProps}
+// 			style={{ ...provided?.draggableProps.style, height: "80px" }}
+// 		>
+// 			<Flex direction="column" gap="2">
+// 				<Flex direction="row" gap="2">
+// 					<Text size="4">{field.label}</Text>
+// 					<Badge className={styles.typeBadge}>
+// 						<Text>{field.fields.length} fields</Text>
+// 					</Badge>
+// 				</Flex>
+// 				<Flex direction="row" gap="2">
+// 					{field.fields.map((child) => {
+// 						const childInfo = FieldTypeToClsMapping[child.type]
+// 						const Icon = childInfo.Icon
+// 						return (
+// 							<Flex key={child.identifier} gap="3">
+// 								<Badge className={styles.typeBadge}>
+// 									<Icon />
+// 									<Text>{childInfo.fieldTypeName}</Text>
+// 								</Badge>
+// 							</Flex>
+// 						)
+// 					})}
+// 				</Flex>
+// 			</Flex>
+// 		</Card>
+// 	)
+// })
+//
+// BasicFieldSection.displayName = "BasicFieldSection"
+
+interface FieldsEditorProps {
+	fieldsOnly: boolean
+}
+
+export const FieldsEditor = memo((props: FieldsEditorProps) => {
+	const { fieldsOnly } = props
+	const { values, setFieldValue } = useFormikContext<FormikUserFormRevision>()
+	// used to conditionally disable dropping on field sections so that a field
+	// using a condition cannot be dropped after the section referencing it
+	const [dropState, dispatch] = useReducer(reducer, values.fields, initializer)
+	const { reorderSection, reorderField } = useFieldReordering()
+
+	useEffect(() => {
+		dispatch({ type: "update", state: initializer(values.fields) })
+	}, [dispatch, values.fields])
+
+	const handleDragStart = useCallback<OnDragStartResponder>((start) => {
+		// validation for ensuring a condition is before the section
+		// when dragging a section occurs in `handleDragEnd`
+
+		// if dragging a field between sections
+		if (start.type === "SECTION") {
+			dispatch({ type: "hold", fieldId: start.draggableId })
+		}
+	}, [])
+
+	const handleDragEnd = useCallback<OnDragEndResponder>(
+		(result) => {
+			const { source, destination, type, reason, draggableId } = result
+			dispatch({ type: "release" })
+
+			if (!destination || reason === "CANCEL") return
+
+			if (type === "ROOT") {
+				reorderSection(dropState, draggableId, source.index, destination.index, values, setFieldValue)
+				return
+			}
+
+			if (type !== "SECTION") throw new Error("Unexpected droppable type.")
+
+			const [sourceSection, srcIndex] = findSection(values.fields, source.droppableId) ?? []
+			const [destinationSection, destIndex] = findSection(values.fields, destination.droppableId) ?? []
+			reorderField(
+				sourceSection,
+				srcIndex,
+				source.index,
+				destinationSection,
+				destIndex,
+				destination.index,
+				setFieldValue,
+			)
+		},
+		[values, reorderField, setFieldValue, reorderSection, dropState],
+	)
+
+	const handleCreateEmptySection = useCallback(
+		(index: number) => {
+			createNewEmptySection(index + 1, values, setFieldValue)
+		},
+		[values, setFieldValue],
+	)
+
+	return (
+		<DragDropContext onDragStart={handleDragStart} onDragEnd={handleDragEnd}>
+			<Droppable droppableId="droppable" type="ROOT">
+				{(droppableProvided) => (
+					<div
+						className="flex flex-col gap-0"
+						ref={droppableProvided.innerRef}
+						{...droppableProvided.droppableProps}
+					>
+						{values.fields.map((field, index) => (
+							<Fragment key={field.identifier}>
+								<FieldSectionWithActions
+									field={field}
+									index={index}
+									dropState={dropState}
+									fieldsOnly={fieldsOnly}
+								/>
+								{!fieldsOnly && (
+									<Button
+										className="mb-4"
+										type="button"
+										variant="soft"
+										accentColor="base"
+										onClick={() => {
+											handleCreateEmptySection(index)
+										}}
+									>
+										<RiIcon icon="RiAddLine" /> Add section
+									</Button>
+								)}
+							</Fragment>
+						))}
+						{droppableProvided.placeholder}
+					</div>
+				)}
+			</Droppable>
+		</DragDropContext>
+	)
+})
+
+FieldsEditor.displayName = "FieldsEditor"

package/src/forms/builder/FormBuilder.stories.tsx

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { SerializedSelectField, SerializedUploadField } from "../typings"
+import { FormBuilder } from "./FormBuilder"
+
+const meta = {
+	title: "Builder/FormBuilder",
+	component: FormBuilder,
+	tags: ["autodocs"],
+} satisfies Meta<typeof FormBuilder>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const BuildNewForm: Story = {
+	args: {
+		onSave: (form) => {
+			alert(JSON.stringify(form, null, 2))
+		},
+		hydrateRevisionWithImages: (revision) => revision,
+	},
+}
+
+export const EditExistingForm: Story = {
+	args: {
+		onSave: (form) => {
+			alert(JSON.stringify(form, null, 2))
+		},
+		hydrateRevisionWithImages: (revision) => revision,
+		revision: {
+			form: "1",
+			created_by: 1,
+			submitted_at: new Date().toISOString(),
+			revision: 1,
+			title: "Test form",
+			description: "This is a test form.",
+			offline_id: "offline_id",
+			fields: [
+				{
+					type: "string",
+					label: "String field",
+					description: "Hint: enter more than 1 characters",
+					required: true,
+					identifier: "string",
+					minimum_length: 2,
+					maximum_length: 10,
+				},
+				{
+					type: "text",
+					label: "Text field",
+					description: null,
+					required: true,
+					identifier: "text",
+					maximum_length: 400,
+				},
+				{
+					type: "boolean",
+					label: "Boolean field",
+					description: null,
+					required: true,
+					identifier: "boolean",
+				},
+				{
+					type: "select",
+					label: "Select field",
+					description: null,
+					required: true,
+					identifier: "select",
+					options: ["option 1", "option 2", "option 3"].map((option) => ({
+						label: option,
+						value: option,
+					})),
+				} satisfies SerializedSelectField,
+			],
+		},
+	},
+}
+
+export const FormWithUploadField: Story = {
+	args: {
+		onSave: (form) => {
+			alert(JSON.stringify(form, null, 2))
+		},
+		hydrateRevisionWithImages: (revision) => revision,
+		revision: {
+			form: "1",
+			created_by: 1,
+			submitted_at: new Date().toISOString(),
+			revision: 1,
+			title: "Test form",
+			description: "This is a test form.",
+			offline_id: "offline_id",
+			fields: [
+				{
+					type: "upload",
+					label: "Upload field",
+					description: null,
+					required: true,
+					maximum_files: 2,
+					identifier: "upload",
+				} satisfies SerializedUploadField,
+			],
+		},
+	},
+}

package/src/forms/builder/FormBuilder.tsx

@@ -0,0 +1,237 @@
+import { Button, Input, RiIcon, Tabs, TextArea, useToast } from "@overmap-ai/blocks"
+import { UserFormRevision } from "@overmap-ai/core"
+import { cx } from "class-variance-authority"
+import { FormikErrors, FormikProvider, useFormik } from "formik"
+import { forwardRef, memo, useCallback, useMemo } from "react"
+
+import { SEVERITY_COLOR_MAPPING } from "../constants"
+import { AnyField, BaseFormElement, formRevisionToSchema, InputWithHelpText, ISchema } from "../fields"
+import { FormRenderer, PatchField } from "../renderer"
+import { hasKeys, validateForm } from "../utils"
+import { CompleteFieldTypeToClsMapping, formId } from "./constants"
+import { FieldsEditor } from "./FieldsEditor"
+import { FormBuilderSaveHandler, FormikUserFormRevision, NewForm } from "./typings"
+import { emptySection, makeConditionalSourceFields, makeIdentifier, wrapRootFieldsWithFieldSection } from "./utils"
+
+const previewSubmit = () => {
+	alert("This is a form preview, your data will not be saved.")
+}
+
+interface FormBuilderProps {
+	onCancel?: () => void
+	onSave: FormBuilderSaveHandler
+	/** A revision of an existing form to edit. To create a new form, pass `undefined`. */
+	revision?: UserFormRevision
+	initialTitle?: string
+	/** @default true */
+	showExplainerText?: boolean
+	/** @default true */
+	showFormTitle?: boolean
+	/** Show and edit non-section fields only. Functionally, these fields will be in a single section with no label
+	 * @default false
+	 */
+	fieldsOnly?: boolean
+	/** Show the Edit and Preview tabs at the top of the component. If false, the preview is entirely inaccessible.
+	 * @default true
+	 */
+	showTabs?: boolean
+	tabsListClassName?: string
+	hydrateRevisionWithImages: (revision: UserFormRevision) => UserFormRevision
+}
+
+export const FormBuilder = memo(
+	forwardRef<HTMLDivElement, FormBuilderProps>((props, ref) => {
+		const {
+			onCancel,
+			onSave,
+			revision,
+			initialTitle,
+			showExplainerText = true,
+			showFormTitle = true,
+			fieldsOnly = false,
+			showTabs = true,
+			tabsListClassName,
+			hydrateRevisionWithImages,
+		} = props
+		const { showError } = useToast()
+
+		const validate = useCallback(
+			(form: FormikUserFormRevision) => {
+				const errors: FormikErrors<FormikUserFormRevision> = {}
+				if (!form.title) {
+					errors.title = "Title is required."
+				}
+
+				if (!form.fields || form.fields.length === 0) {
+					errors.fields = "At least one field is required."
+				}
+
+				let fieldsToValidate: BaseFormElement[] = []
+				for (const [sectionIndex, section] of form.fields.entries()) {
+					// Section settings (conditional and condition)
+					const fieldCls = CompleteFieldTypeToClsMapping.section
+					const sectionSettings = fieldCls
+						.getFieldCreationSchema(
+							makeConditionalSourceFields(form.fields, sectionIndex),
+							`fields.${sectionIndex}`,
+						)
+						.map((field) => field.field)
+
+					fieldsToValidate = [...fieldsToValidate, ...sectionSettings]
+
+					// Field settings (required, min/max values, options, etc.)
+					for (const [fieldIndex, field] of section.fields.entries()) {
+						const fieldCls = CompleteFieldTypeToClsMapping[field.type]
+						const fieldSettings: AnyField[] = fieldCls
+							.getFieldCreationSchema(`fields.${sectionIndex}.fields.${fieldIndex}`)
+							.map((field) => field.field)
+
+						fieldsToValidate = [...fieldsToValidate, ...fieldSettings]
+					}
+				}
+
+				const fieldErrors = validateForm(
+					{
+						title: "Validate form builder",
+						fields: fieldsToValidate,
+						meta: { readonly: true },
+					},
+					form,
+				)
+				if (fieldErrors) {
+					errors.fields = fieldErrors.fields
+				}
+
+				if (hasKeys(errors)) {
+					showError({
+						title: "Some form settings are invalid",
+						description: "Please check settings highlighted in red.",
+					})
+					return errors
+				}
+			},
+			[showError],
+		)
+
+		const initialValues: NewForm = useMemo(
+			() => ({
+				title: initialTitle ?? "",
+				description: "",
+				fields: [{ ...emptySection(makeIdentifier(null, "")), label: "" }],
+			}),
+			[initialTitle],
+		)
+
+		// Add attachments as file promises to revision fields
+		const revisionWithImages = revision ? hydrateRevisionWithImages(revision) : undefined
+
+		const formik = useFormik<FormikUserFormRevision>({
+			initialValues: wrapRootFieldsWithFieldSection(revisionWithImages) ?? initialValues,
+			validate,
+			onSubmit: onSave,
+			validateOnChange: false,
+			validateOnBlur: false,
+		})
+
+		const previewSchema: ISchema = useMemo(() => formRevisionToSchema(formik.values), [formik.values])
+
+		return (
+			<Tabs.Root ref={ref} defaultValue="edit">
+				<div className="flex flex-col gap-2">
+					{showTabs && (
+						<Tabs.List
+							className={cx("sticky top-0 z-[2000] flex bg-(--color-background)", tabsListClassName)}
+						>
+							<Tabs.Trigger className="grow" value="edit">
+								<div className="flex items-center gap-2">
+									<RiIcon icon="RiPencilLine" />
+									Edit form
+								</div>
+							</Tabs.Trigger>
+							<Tabs.Trigger className="grow" value="preview">
+								<div className="flex items-center gap-2">
+									<RiIcon icon="RiEyeLine" />
+									Preview form
+								</div>
+							</Tabs.Trigger>
+						</Tabs.List>
+					)}
+					<Tabs.Content value="edit">
+						{showExplainerText && (
+							<span>
+								Create your form using various field types. Sections can be{" "}
+								<strong>conditionally rendered</strong> based on{" "}
+								<strong>answers to fields in preceding sections. </strong>
+							</span>
+						)}
+
+						<form className="mt-3 flex flex-col gap-2" id={formId} onSubmit={formik.handleSubmit}>
+							<FormikProvider value={formik}>
+								{showFormTitle && (
+									<>
+										<PatchField
+											name="title"
+											render={({ setValue, value, meta }) => (
+												<InputWithHelpText severity="danger" helpText={meta.error ?? null}>
+													<Input.Root
+														variant="outline"
+														size="lg"
+														accentColor={
+															meta.error ? SEVERITY_COLOR_MAPPING.danger : "primary"
+														}
+													>
+														<Input.Field
+															placeholder="Form title"
+															value={value as string}
+															onChange={(event) => {
+																setValue(event.target.value)
+															}}
+															maxLength={100}
+														/>
+													</Input.Root>
+												</InputWithHelpText>
+											)}
+										/>
+										<PatchField
+											name="description"
+											render={({ setValue, value }) => (
+												<TextArea
+													className="field-sizing-content"
+													placeholder="Explain the purpose of this form"
+													value={value as string}
+													onChange={(event) => {
+														setValue(event.target.value)
+													}}
+													resize="vertical"
+													maxLength={1000}
+												/>
+											)}
+										/>
+									</>
+								)}
+								<FieldsEditor fieldsOnly={fieldsOnly} />
+								<span
+									data-accent-color={SEVERITY_COLOR_MAPPING.danger}
+									className="text-xs text-(--accent-a11)"
+								>
+									{typeof formik.errors.fields === "string" && formik.errors.fields}
+								</span>
+							</FormikProvider>
+							<div className="flex items-center justify-end gap-2">
+								{onCancel && (
+									<Button type="button" variant="solid" accentColor="base" onClick={onCancel}>
+										Cancel
+									</Button>
+								)}
+								<Button type="submit">Save form</Button>
+							</div>
+						</form>
+					</Tabs.Content>
+					<Tabs.Content value="preview">
+						<FormRenderer schema={previewSchema} onSubmit={previewSubmit} hideTitle={!showFormTitle} />
+					</Tabs.Content>
+				</div>
+			</Tabs.Root>
+		)
+	}),
+)

package/src/forms/builder/constants.ts

@@ -0,0 +1,18 @@
+import { FieldSection } from "../fields"
+import { FieldTypeToClsMapping } from "../fields/constants"
+import { FieldTypeIdentifier } from "../typings"
+
+export const formId = "form-builder"
+
+export const fieldsToChoose = [
+	["string", "text"],
+	["select", "multi-select", "upload", "qr"],
+	["boolean", "date", "number", "multi-string"],
+] satisfies FieldTypeIdentifier[][]
+
+export const indexOfLastFieldGroup = fieldsToChoose.length - 1
+
+export const CompleteFieldTypeToClsMapping = {
+	...FieldTypeToClsMapping,
+	section: FieldSection,
+}

package/src/forms/builder/hooks.tsx

@@ -0,0 +1,24 @@
+import { ReactNode, useMemo } from "react"
+
+import { FieldTypeToClsMapping } from "../fields/constants"
+import { FieldTypeIdentifier } from "../typings"
+import { fieldsToChoose } from "./constants"
+
+export const useFieldTypeItems = (onSelect: (type: Exclude<FieldTypeIdentifier, "section">) => void = () => null) => {
+	return useMemo(() => {
+		return fieldsToChoose.map((fieldGroup) => {
+			return fieldGroup.map((identifier) => {
+				const field = FieldTypeToClsMapping[identifier]
+				const Icon = field.Icon as () => ReactNode
+				return {
+					children: field.fieldTypeName,
+					leftSlot: <Icon />,
+					value: identifier,
+					onSelect: () => {
+						onSelect(identifier)
+					},
+				}
+			})
+		})
+	}, [onSelect])
+}

package/src/forms/builder/index.ts

@@ -0,0 +1,2 @@
+export * from "./FormBuilder"
+export * from "./typings"