@overmap-ai/forms 0.0.1-master.3

package/src/forms/builder/typings.ts

@@ -0,0 +1,18 @@
+import { UserFormRevision } from "@overmap-ai/core"
+
+import { SerializedFieldSection } from "../typings"
+
+export type NewForm = Pick<UserFormRevision<SerializedFieldSection>, "description" | "title" | "fields">
+
+export type FormBuilderSaveHandler = (form: NewForm | UserFormRevision) => void
+
+/** The `FormBuilder` can either be used to edit an existing form or create a new one.
+ *
+ * The only difference between the two is that new forms do not have `id` attributes.
+ */
+export type FormikUserFormRevision = UserFormRevision<SerializedFieldSection> | NewForm
+
+// parentPath + "." + index = field path
+/** Using `lodash.get` and `lodash.set`, we can set and get attributes of nested objects using a string path. This is 
+used to get and set attributes of the `fields` of a `SerializedFieldSection` object. */
+export type NestedFieldPath = "fields" | `fields.${number}.fields`

package/src/forms/builder/utils.ts

@@ -0,0 +1,229 @@
+import { useToast } from "@overmap-ai/blocks"
+import { ISerializedOnlyField, UserFormRevision } from "@overmap-ai/core"
+import { slugify } from "@overmap-ai/core"
+import { FormikHelpers } from "formik"
+import get from "lodash.get"
+import { useCallback } from "react"
+
+import { ISerializedField, SerializedFieldSection } from "../typings"
+import { DropState } from "./DropDispatch"
+import { FormikUserFormRevision, NestedFieldPath } from "./typings"
+
+export const emptySection = (id = "", fields = [] as ISerializedOnlyField[]): SerializedFieldSection => ({
+	type: "section",
+	fields,
+	identifier: id,
+	label: null,
+	condition: null,
+	conditional: false,
+})
+
+export const wrapRootFieldsWithFieldSection = (
+	revision?: UserFormRevision,
+): UserFormRevision<SerializedFieldSection> | undefined => {
+	if (!revision) return undefined
+	const fields = revision.fields
+	let pending: ISerializedOnlyField[] = []
+	const sections: SerializedFieldSection[] = []
+
+	for (const field of fields) {
+		if (field.type === "section") {
+			if (pending.length > 0) {
+				sections.push(emptySection(`AUTO_section-${fields.indexOf(field)}`, pending))
+				pending = []
+			}
+			sections.push(field)
+		} else {
+			pending.push(field)
+		}
+	}
+	if (pending.length > 0) {
+		sections.push(emptySection("AUTO_section-last", pending))
+	}
+
+	// ensure the description isn't null
+	return { ...revision, fields: sections, description: revision.description ?? "" }
+}
+
+export function reorder<T>(list: T[], source: number, destination: number): T[] {
+	const result = Array.from(list)
+	const [removed] = result.splice(source, 1)
+
+	if (!removed) throw new Error("Could not find field to reorder.")
+	result.splice(destination, 0, removed)
+
+	return result
+}
+
+export function replace<T>(list: T[], index: number, value: T): T[] {
+	const result = Array.from(list)
+	result[index] = value
+	return result
+}
+
+export function insert<T>(list: T[] | undefined, index: number, value: T): T[] {
+	const result = Array.from(list ?? [])
+	result.splice(index, 0, value)
+	return result
+}
+
+export function remove<T>(list: T[], index: number): T[] {
+	const result = Array.from(list)
+	result.splice(index, 1)
+	return result
+}
+
+export const makeIdentifier = (existing: unknown, label: string): string => {
+	if (typeof existing === "string" && existing.length > 0) return existing
+
+	// add a timestamp to the end of the slug to make it unique
+	const now = new Date()
+	return `${slugify(label)}-${now.getTime()}`
+}
+
+export const findFieldByIdentifier = (fields: ISerializedField[], identifier?: string): ISerializedField | null => {
+	if (!identifier) return null
+	for (const field of fields) {
+		if (field.type === "section") {
+			const result = findFieldByIdentifier(field.fields, identifier)
+			if (result) return result
+		} else if (field.identifier === identifier) {
+			return field
+		}
+	}
+	return null
+}
+
+export const makeConditionalSourceFields = (sections: SerializedFieldSection[], index: number) => {
+	return sections.filter((_, i) => i < index).flatMap((field) => field.fields)
+}
+
+export type NewFieldInitialValues = Omit<ISerializedField, "identifier"> & {
+	label: string
+}
+
+export const createNewField = (
+	parentPath: NestedFieldPath,
+	index: number,
+	initialValues: NewFieldInitialValues,
+	values: FormikUserFormRevision,
+	setFieldValue: FormikHelpers<unknown>["setFieldValue"],
+) => {
+	const { label } = initialValues
+	const newField = {
+		...initialValues,
+		identifier: makeIdentifier(null, label),
+	} as ISerializedField
+
+	const parent = get(values, parentPath) as SerializedFieldSection[] | undefined
+	if (parent === undefined) {
+		throw new Error("Parent path must point to an existing field.")
+	}
+
+	if (!Array.isArray(parent)) {
+		throw new Error("Parent path must point to an array.")
+	}
+
+	const updatedFields = insert(parent, index, newField)
+	void setFieldValue(parentPath, updatedFields).then()
+}
+
+export const createNewEmptySection = (
+	index: number,
+	values: FormikUserFormRevision,
+	setFieldValue: FormikHelpers<unknown>["setFieldValue"],
+) => {
+	const initialValues = {
+		...emptySection(),
+		label: "",
+	}
+	createNewField("fields", index, initialValues, values, setFieldValue)
+}
+
+// Custom hook that returns a function which attempts to reorder a section through drag and drop or arrow buttons.
+export const useFieldReordering = () => {
+	const { showError } = useToast()
+	const reorderSection = useCallback(
+		(
+			dropState: DropState,
+			sectionId: string,
+			sectionIndex: number,
+			destinationIndex: number,
+			values: FormikUserFormRevision,
+			setFieldValue: FormikHelpers<unknown>["setFieldValue"],
+		) => {
+			const state = dropState[sectionId]
+			if (!state) throw new Error("Could not find section context.")
+
+			let dest =
+				typeof state.conditionIndex !== "undefined"
+					? // cannot move a section with a condition before the condition's field
+						Math.max(state.conditionIndex + 1, destinationIndex)
+					: destinationIndex
+
+			// check if this section contains another section's condition
+			for (const section of Object.values(dropState)) {
+				if (section.conditionIndex === sectionIndex) {
+					// ensure condition field is above the section referencing it
+					dest = Math.min(dest, section.index - 1)
+				}
+			}
+
+			// A section with conditions is above the fields it references
+			if (dest !== destinationIndex) {
+				showError({
+					title: "Could not reorder sections",
+					description: "Sections with conditions must be below the fields they reference.",
+				})
+				return
+			}
+
+			// Good to reorder
+			void setFieldValue("fields", reorder(values.fields, sectionIndex, dest))
+		},
+		[showError],
+	)
+
+	const reorderField = useCallback(
+		(
+			srcSection: SerializedFieldSection | undefined,
+			srcSectionIndex: string | number | undefined,
+			srcFieldIndex: number,
+			destSection: SerializedFieldSection | undefined,
+			destSectionIndex: string | number | undefined,
+			destFieldIndex: number,
+			setFieldValue: FormikHelpers<unknown>["setFieldValue"],
+		) => {
+			if (!srcSection?.fields || !destSection) throw new Error("Could not find section with fields.")
+
+			if (srcSection.identifier === destSection.identifier) {
+				void setFieldValue(
+					`fields.${srcSectionIndex}.fields`,
+					reorder(srcSection.fields, srcFieldIndex, destFieldIndex),
+				).then()
+			} else {
+				const removed = srcSection.fields[srcFieldIndex]
+				if (!removed) throw new Error("Could not find field to reorder.")
+
+				// Check if the field is being used as a condition in its new section
+				if (destSection.condition?.identifier === removed.identifier) {
+					showError({
+						title: "Could not reorder field",
+						description: "Field must be above the section whose condition references it.",
+					})
+					return
+				}
+
+				// Good to reorder
+				void setFieldValue(`fields.${srcSectionIndex}.fields`, remove(srcSection.fields, srcFieldIndex)).then()
+				void setFieldValue(
+					`fields.${destSectionIndex}.fields`,
+					insert(destSection.fields, destFieldIndex, removed),
+				).then()
+			}
+		},
+		[showError],
+	)
+
+	return { reorderSection, reorderField }
+}

package/src/forms/constants.ts

@@ -0,0 +1,9 @@
+export const SHORT_TEXT_FIELD_MAX_LENGTH = 500
+export const LONG_TEXT_FIELD_MAX_LENGTH = 10000
+
+export const SEVERITY_COLOR_MAPPING: Record<"danger" | "warning" | "info" | "success", string> = {
+	danger: "danger",
+	warning: "warning",
+	info: "base",
+	success: "success",
+}

package/src/forms/constantsJsx.tsx

@@ -0,0 +1,67 @@
+import { IconButton, RiIcon } from "@overmap-ai/blocks"
+import saveAs from "file-saver"
+import { Dispatch, memo, MouseEvent, SetStateAction, useCallback } from "react"
+
+interface FullScreenImagePreviewProps {
+	file: File
+	url: string
+	name: string
+	setShowPreview: Dispatch<SetStateAction<boolean>>
+}
+
+export const FullScreenImagePreview = memo((props: FullScreenImagePreviewProps) => {
+	const { file, url, name, setShowPreview } = props
+
+	const handleDownload = useCallback(
+		(event: MouseEvent<HTMLButtonElement>) => {
+			event.stopPropagation()
+			const blob = new Blob([file])
+			saveAs(blob, name)
+		},
+		[name, file],
+	)
+
+	return (
+		<>
+			<button
+				className="fixed top-0 left-0 z-[5000] h-full w-full bg-[rgba(0,0,0,0.85)] bg-black"
+				type="button"
+				onClick={() => {
+					setShowPreview(false)
+				}}
+			>
+				<img
+					className="absolute top-[50%] left-[50%] z-[5001] max-h-[calc(100%-120px)] max-w-svw translate-x-[-50%] translate-y-[50%] object-contain"
+					src={url}
+					alt={name}
+					onClick={(e) => {
+						e.stopPropagation()
+					}}
+				/>
+			</button>
+			<div className="fixed top-0 left-0 z-[5001] flex w-full items-center bg-(--color-background)">
+				<IconButton
+					className="min-w-[50px]"
+					variant="soft"
+					aria-label="Exit preview"
+					onClick={() => {
+						setShowPreview(false)
+					}}
+				>
+					<RiIcon icon="RiArrowLeftLine" />
+				</IconButton>
+				<span className="grow text-center">{name}</span>
+				<IconButton
+					className="min-w-[50px]"
+					variant="soft"
+					aria-label={`Download ${name}`}
+					onClick={handleDownload}
+				>
+					<RiIcon icon="RiDownload2Line" />
+				</IconButton>
+			</div>
+		</>
+	)
+})
+
+FullScreenImagePreview.displayName = "FullScreenImagePreview"

package/src/forms/fields/BaseField/BaseField.ts

@@ -0,0 +1,152 @@
+import { ISerializedOnlyField } from "@overmap-ai/core"
+import { ChangeEvent, ReactNode } from "react"
+
+import { FormikUserFormRevision } from "../../builder"
+import {
+	BaseSerializedField,
+	BaseSerializedObject,
+	FieldTypeIdentifier,
+	FieldValue,
+	Form,
+	ISerializedField,
+} from "../../typings"
+import { FieldSection } from "../FieldSection"
+import { AnyField, GetInputProps, InputFieldLevelValidator, InputFormLevelValidator } from "../typings"
+import { FieldOptions } from "./typings"
+
+// TODO: These types redefine ISerializedField and related types.
+//  Looks like they can be merged.
+
+// TODO: "Element" implies an instantiated component in React.
+export abstract class BaseFormElement<TIdentifier extends FieldTypeIdentifier = FieldTypeIdentifier> {
+	public readonly type: TIdentifier
+	readonly identifier: string
+	public readonly description: string | null
+
+	protected constructor(options: BaseSerializedObject) {
+		const { description = null, identifier, type } = options
+		this.identifier = identifier
+		this.description = description
+		this.type = type as TIdentifier
+	}
+
+	getId(): string {
+		return this.identifier
+	}
+
+	abstract getInput(props: GetInputProps<this>): ReactNode
+
+	static deserialize(_data: ISerializedField): AnyField | FieldSection {
+		throw new Error(`${this.name} must implement deserialize.`)
+	}
+
+	protected _serialize(): BaseSerializedObject<TIdentifier> {
+		if (!this.identifier) {
+			throw new Error("Field identifier must be set before serializing.")
+		}
+		return {
+			type: this.type,
+			identifier: this.identifier,
+			description: this.description,
+		}
+	}
+}
+
+export const emptyBaseField = {
+	label: "",
+	description: "",
+	required: false,
+}
+
+export interface FieldCreationSchemaObject {
+	field: AnyField
+	showDirectly: boolean
+}
+
+export abstract class BaseField<
+	TValue extends FieldValue,
+	TIdentifier extends FieldTypeIdentifier = FieldTypeIdentifier,
+> extends BaseFormElement<TIdentifier> {
+	static readonly fieldTypeName: string
+	static readonly fieldTypeDescription: string
+
+	public readonly required: boolean
+	private readonly formValidators: InputFormLevelValidator<TValue>[]
+	private readonly fieldValidators: InputFieldLevelValidator<TValue>[]
+	public readonly label: string
+	public readonly image: File | Promise<File> | undefined
+
+	/**
+	 * By default, validation doesn't execute on `onChange` events when editing fields
+	 * until the field has been `touched`. This can be overridden by setting this to `false`
+	 * if you want to validate on every `onChange` event. This is important for fields like booleans
+	 * which don't have a `onBlur` event (which is used to set the `touched` state).
+	 */
+	public readonly onlyValidateAfterTouched: boolean = true
+
+	protected constructor(options: FieldOptions<TValue>) {
+		const { label, required, image, fieldValidators = [], formValidators = [], ...base } = options
+		super(base)
+		this.label = label
+		this.required = required
+		this.image = image
+		this.fieldValidators = fieldValidators
+		this.formValidators = formValidators
+	}
+
+	public static getFieldCreationSchema(): FieldCreationSchemaObject[] {
+		return []
+	}
+
+	protected isBlank(value: TValue | undefined): boolean {
+		return value === null || value === undefined || value === ""
+	}
+
+	public getValueFromChangeEvent(event: ChangeEvent<HTMLInputElement>): TValue {
+		return event.target.value as unknown as TValue
+	}
+
+	public getError(value: TValue, allValues?: Form | FormikUserFormRevision): string | undefined {
+		if (this.required && this.isBlank(value)) {
+			return "This field is required."
+		}
+		for (const validator of this.getFieldValidators()) {
+			const error = validator(value)
+			if (error) return error
+		}
+		if (allValues) {
+			for (const validator of this.getFormValidators()) {
+				const error = validator(value, allValues)
+				if (error) return error
+			}
+		}
+	}
+
+	// TODO: We can probably combine _serialize and serialize.
+	protected _serialize(): BaseSerializedField<TIdentifier> {
+		return {
+			...super._serialize(),
+			label: this.label,
+			required: this.required,
+			image: this.image,
+		}
+	}
+
+	abstract serialize(): ISerializedOnlyField
+
+	public getFieldValidators(): InputFieldLevelValidator<TValue>[] {
+		return [...this.fieldValidators]
+	}
+
+	public getFormValidators(): InputFormLevelValidator<TValue>[] {
+		return [...this.formValidators]
+	}
+
+	public encodeValueToJson(value: TValue) {
+		return JSON.stringify(value)
+	}
+
+	public decodeJsonToValue(json: string): TValue {
+		return JSON.parse(json) as TValue
+	}
+}

package/src/forms/fields/BaseField/hooks.tsx

@@ -0,0 +1,60 @@
+import { useField } from "formik"
+import { ChangeEventHandler, FocusEventHandler, useMemo } from "react"
+
+import { Severity, ValueOfField } from "../../typings"
+import { AnyField, ComponentProps } from "../typings"
+
+// Wrapper for Formik's useField hook that returns the field's props, meta, and helpers.
+export const useFormikInput = <TField extends AnyField>(props: ComponentProps<TField>) => {
+	const { id, field, formId, size, showInputOnly, internal, ...rest } = props
+	const [fieldProps, meta, helpers] = useField<ValueOfField<TField>>(field.getId())
+	const { touched } = meta
+	const helpText = meta.error ?? field.description
+	const severity: Severity | undefined = meta.error ? "danger" : undefined
+	const inputId = id ?? `${formId}-${field.getId()}-input`
+	const labelId = `${inputId}-label`
+	const label = field.required ? `${field.label} *` : field.label
+
+	// adds field-level validation to onChange and onBlur events
+	// this is necessary because Formik's useField hook does not support field-level validation
+	const fieldPropsWithValidation: typeof fieldProps = useMemo(() => {
+		const handleChange: ChangeEventHandler<HTMLInputElement> = (e) => {
+			const value = field.getValueFromChangeEvent(e) as ValueOfField<TField>
+			void helpers.setValue(value, false).then()
+			// only validate onChange if the field has been touched
+			if (touched || !field.onlyValidateAfterTouched) {
+				helpers.setError(field.getError(value))
+			}
+		}
+
+		const handleBlur: FocusEventHandler<HTMLInputElement> = (e) => {
+			void helpers.setTouched(true, false).then()
+			helpers.setError(field.getError(field.getValueFromChangeEvent(e)))
+		}
+
+		return {
+			...fieldProps,
+			onChange: handleChange,
+			onBlur: handleBlur,
+		}
+	}, [field, fieldProps, helpers, touched])
+
+	console.debug("severity", severity)
+
+	return [
+		{
+			helpText,
+			size,
+			severity,
+			inputId,
+			labelId,
+			label,
+			showInputOnly,
+			internal,
+			fieldProps: fieldPropsWithValidation,
+			helpers,
+			field,
+		},
+		{ ...rest, "aria-labelledby": labelId },
+	] as const
+}

package/src/forms/fields/BaseField/index.ts

@@ -0,0 +1,4 @@
+export * from "./BaseField"
+export * from "./hooks"
+export * from "./layouts"
+export * from "./typings"

package/src/forms/fields/BaseField/layouts.tsx

@@ -0,0 +1,100 @@
+import { Text, TextSize } from "@overmap-ai/blocks"
+import { cx } from "class-variance-authority"
+import { ReactElement, ReactNode, useEffect, useState } from "react"
+
+import { SEVERITY_COLOR_MAPPING } from "../../constants"
+import { FullScreenImagePreview } from "../../constantsJsx"
+import { Severity } from "../../typings"
+
+interface InputWithLabelProps {
+	size?: TextSize
+	severity: Severity | undefined
+	inputId: string
+	labelId: string
+	label: string
+	image: File | Promise<File> | undefined
+	children: ReactNode
+	className?: string
+}
+export const InputWithLabel = (props: InputWithLabelProps) => {
+	const { className, label, children, size, severity, inputId, labelId, image } = props
+	const [resolvedImage, setResolvedImage] = useState<File | undefined>(undefined)
+	const [showImagePreview, setShowImagePreview] = useState<boolean>(false)
+
+	const color = severity ? SEVERITY_COLOR_MAPPING[severity] : "base"
+
+	console.debug(severity, color)
+
+	useEffect(() => {
+		if (image instanceof Promise) {
+			image.then(setResolvedImage).catch(console.error)
+		} else {
+			setResolvedImage(image)
+		}
+	}, [image])
+
+	const resolvedImageURL = resolvedImage ? URL.createObjectURL(resolvedImage) : undefined
+
+	return (
+		<div className="flex flex-col gap-2">
+			{resolvedImage && (
+				<>
+					<img
+						className="h-[100px] w-full min-w-[300px] cursor-pointer rounded-md object-cover"
+						src={resolvedImageURL}
+						alt={resolvedImage.name}
+						onClick={() => {
+							setShowImagePreview(true)
+						}}
+					/>
+					{showImagePreview && (
+						<FullScreenImagePreview
+							file={resolvedImage}
+							url={resolvedImageURL!}
+							name={resolvedImage.name}
+							setShowPreview={setShowImagePreview}
+						/>
+					)}
+				</>
+			)}
+
+			<label className={cx(className, "flex flex-col gap-1")} htmlFor={inputId}>
+				<Text accentColor={color} size={size} id={labelId} weight="medium">
+					{label}
+				</Text>
+				{children}
+			</label>
+		</div>
+	)
+}
+
+interface InputWithHelpTextProps {
+	severity: Severity | undefined
+	helpText: string | null
+	children: ReactElement
+}
+
+export const InputWithHelpText = (props: InputWithHelpTextProps) => {
+	const { helpText, children, severity } = props
+
+	const color = severity ? SEVERITY_COLOR_MAPPING[severity] : "base"
+
+	return (
+		<div className="flex flex-col gap-1">
+			{children}
+			<div className="flex flex-col w-full">
+				<Text accentColor={color} size="xs">
+					{helpText}
+				</Text>
+			</div>
+		</div>
+	)
+}
+
+interface InputWithLabelAndHelpTextProps extends InputWithHelpTextProps {
+	children: ReactElement<InputWithLabelProps>
+}
+export const InputWithLabelAndHelpText = (props: InputWithLabelAndHelpTextProps) => {
+	const { children, ...restProps } = props
+	return <InputWithHelpText {...restProps}>{children}</InputWithHelpText>
+}

package/src/forms/fields/BaseField/typings.ts

@@ -0,0 +1,9 @@
+import { BaseSerializedField } from "../../typings"
+import { InputFieldLevelValidator, InputFormLevelValidator } from "../typings"
+
+export interface FieldOptions<TValue> extends BaseSerializedField {
+	fieldValidators?: InputFieldLevelValidator<TValue>[]
+	formValidators?: InputFormLevelValidator<TValue>[]
+}
+
+export type ChildFieldOptions<TValue> = Omit<FieldOptions<TValue>, "type">