@overmap-ai/forms 0.0.1-master.3

package/src/forms/renderer/FormRenderer/FormRenderer.stories.tsx

@@ -0,0 +1,142 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { formRevisionToSchema, PartialFormRevision } from "../../fields"
+import { FormRenderer } from "./FormRenderer"
+
+const meta = {
+	title: "Renderer/FromRenderer",
+	component: FormRenderer,
+	tags: ["autodocs"],
+} satisfies Meta<typeof FormRenderer>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const partialFormRevision: PartialFormRevision = {
+	title: "Test form",
+	description: "This is a test form",
+	fields: [
+		{
+			type: "section",
+			label: "Section",
+			condition: null,
+			conditional: false,
+			identifier: "section",
+			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",
+					required: true,
+					identifier: "text",
+					maximum_length: 400,
+				},
+				{
+					type: "boolean",
+					label: "Boolean field",
+					required: true,
+					identifier: "boolean",
+					description: "Hint: enter true to pass validation and open and new section",
+				},
+				{
+					type: "select",
+					label: "Select field",
+					required: true,
+					identifier: "select",
+					options: [
+						{ label: "option 1", value: "option 1" },
+						{ label: "option 2", value: "option 2" },
+					],
+				},
+				{
+					type: "multi-select",
+					label: "Multi-select field",
+					required: true,
+					identifier: "multi_select",
+					options: [
+						{ label: "option 1", value: "option 1" },
+						{ label: "option 2", value: "option 2" },
+					],
+				},
+				{
+					type: "multi-string",
+					label: "Multi-string field",
+					description: "Used to generate options",
+					required: true,
+					identifier: "multi_string",
+					minimum_length: 2,
+					maximum_length: 10,
+				},
+				{
+					type: "upload",
+					label: "Upload Field",
+					description: "Used to upload files",
+					required: true,
+					identifier: "upload",
+					maximum_files: 10,
+				},
+				{
+					type: "qr",
+					label: "QR Field",
+					description: "Used to scan QR codes",
+					required: true,
+					identifier: "qr",
+				},
+			],
+		},
+		{
+			type: "section",
+			label: "Another section",
+			identifier: "another_section",
+			condition: {
+				identifier: "boolean",
+				value: true,
+			},
+			conditional: true,
+			fields: [
+				{
+					type: "select",
+					label: "Select field",
+					required: true,
+					identifier: "select2",
+					options: [
+						{ label: "option 1", value: "option 1" },
+						{ label: "option 2", value: "option 2" },
+					],
+				},
+			],
+		},
+	],
+}
+
+export const RenderForSubmission: Story = {
+	args: {
+		schema: formRevisionToSchema(partialFormRevision),
+		cancelText: "Cancel",
+		onSubmit: () => {
+			alert("validation passed")
+		},
+	},
+}
+
+export const RenderForViewing: Story = {
+	args: {
+		schema: formRevisionToSchema(partialFormRevision, { readonly: true }),
+		values: {
+			string: "hello",
+			text: "world",
+			boolean: "true",
+			select: "option 1",
+			multi_string: ["hello", "world"],
+			multi_select: ["option 1", "option 2"],
+		},
+	},
+}

package/src/forms/renderer/FormRenderer/FormRenderer.tsx

@@ -0,0 +1,135 @@
+import { Button, ButtonProps, Card, Heading, RiIcon, Text } from "@overmap-ai/blocks"
+import { cx } from "class-variance-authority"
+import { FormikProvider, useFormik } from "formik"
+import { forwardRef, memo, useEffect, useMemo } from "react"
+
+import { SEVERITY_COLOR_MAPPING } from "../../constants"
+import { ISchema, useFieldInputs } from "../../fields"
+import { Form } from "../../typings"
+import { initialFormValues, validateForm } from "../../utils"
+
+interface FormRendererProps {
+	/** The schema of the form the render */
+	schema: ISchema
+	/** Initial values of the form */
+	values?: Form
+	onSubmit?: (values: Form) => Promise<void> | void
+	/** @default "Submit" */
+	submitText?: string
+	/** The text of the cancel button (hidden by default)
+	 * @default null
+	 */
+	cancelText?: string
+	onCancel?: () => void
+	onDirty?: () => void
+	onDirtyChange?: (dirty: boolean) => void
+	/** Hide the form description
+	 * @default false */
+	hideDescription?: boolean
+	/** Hide the title (and description)
+	 * @default false
+	 */
+	hideTitle?: boolean
+	className?: string
+	buttonProps?: Omit<ButtonProps, "children">
+}
+
+const defaultHandleSubmit = () => {
+	throw new Error("onSubmit must be provided if form is not readonly.")
+}
+
+export const FormRenderer = memo(
+	forwardRef<HTMLFormElement, FormRendererProps>((props, ref) => {
+		const {
+			schema,
+			values = {},
+			onSubmit = defaultHandleSubmit,
+			submitText = "Submit",
+			cancelText,
+			onCancel,
+			onDirty,
+			onDirtyChange,
+			// if the title isn't provided, hide it by default
+			hideTitle = !schema.title,
+			hideDescription,
+			className,
+			buttonProps,
+		} = props
+		const { readonly } = schema.meta
+
+		// randomly generate a form id to ensure field ids are unique
+		const formId = useMemo(() => crypto.randomUUID(), [])
+
+		const formik = useFormik<Form>({
+			initialValues: initialFormValues(schema.fields, values),
+			onSubmit,
+			validate: (form) => validateForm(schema, form),
+			// only validate the entire form on submit
+			validateOnBlur: false,
+			validateOnChange: false,
+		})
+		const { dirty } = formik
+
+		const Title = useMemo(
+			() => (typeof schema.title === "string" ? <Heading size="lg">{schema.title}</Heading> : schema.title),
+			[schema.title],
+		)
+
+		const Description = useMemo(
+			() =>
+				typeof schema.description === "string" ? (
+					<Text accentColor="base">{schema.description}</Text>
+				) : (
+					schema.description
+				),
+			[schema.description],
+		)
+
+		const inputs = useFieldInputs(schema.fields, { formId, disabled: readonly })
+
+		useEffect(() => {
+			if (dirty && onDirty) onDirty()
+			if (onDirtyChange) onDirtyChange(dirty)
+		}, [dirty, onDirty, onDirtyChange])
+
+		return (
+			<FormikProvider value={formik}>
+				<form
+					id={formId}
+					ref={ref}
+					className={cx(className, "flex flex-col gap-2")}
+					onSubmit={formik.handleSubmit}
+				>
+					{!hideTitle && (
+						<Card>
+							<div className="flex flex-col gap-1">
+								{Title}
+								{!hideDescription && Description}
+							</div>
+						</Card>
+					)}
+					{inputs}
+					{!readonly && (
+						<div className="flex items-center justify-end gap-2">
+							{cancelText && (
+								<Button
+									accentColor={SEVERITY_COLOR_MAPPING.danger}
+									{...buttonProps}
+									type="button"
+									onClick={onCancel}
+								>
+									<RiIcon icon="RiCloseLine" />
+									{cancelText}
+								</Button>
+							)}
+							<Button {...buttonProps} type="submit" disabled={!formik.isValid} accentColor="success">
+								<RiIcon icon="RiCheckLine" />
+								{submitText}
+							</Button>
+						</div>
+					)}
+				</form>
+			</FormikProvider>
+		)
+	}),
+)

package/src/forms/renderer/PatchForm/Field.tsx

@@ -0,0 +1,41 @@
+import { FieldMetaProps, useField, useFormikContext } from "formik"
+import { memo, ReactNode, useMemo } from "react"
+
+import { FieldValue } from "../../typings"
+
+interface RenderArgs {
+	value: FieldValue
+	meta: FieldMetaProps<unknown>
+	/** Intermediate changes to the field value */
+	setValue: (value: FieldValue) => void
+	/** EX: when the onBlur event is fired */
+	patchValue: () => void
+}
+
+interface PatchFieldProps {
+	name: string
+	render: (args: RenderArgs) => ReactNode
+}
+
+export const PatchField = memo((props: PatchFieldProps) => {
+	const { name, render } = props
+	const { submitForm } = useFormikContext()
+	const [fieldProps, _meta, helpers] = useField<FieldValue>(name)
+
+	const ret = useMemo(() => {
+		const setValue = (value: FieldValue) => {
+			void helpers.setValue(value, false)
+		}
+		return render({
+			value: fieldProps.value,
+			meta: _meta,
+			setValue,
+			patchValue: () => {
+				void submitForm()
+			},
+		})
+	}, [render, fieldProps.value, _meta, submitForm, helpers])
+	return <>{ret}</>
+})
+
+PatchField.displayName = "PatchField"

package/src/forms/renderer/PatchForm/PatchForm.stories.tsx

@@ -0,0 +1,91 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { formRevisionToSchema, PartialFormRevision } from "../../fields"
+import { PatchField } from "./Field"
+import { PatchFormProvider } from "./Provider"
+
+const partialFormRevision: PartialFormRevision = {
+	title: "Test form",
+	description: "This is a test form",
+	fields: [
+		{
+			type: "section",
+			label: "Section",
+			condition: null,
+			conditional: false,
+			identifier: "section",
+			fields: [
+				{
+					type: "string",
+					label: "String field",
+					required: true,
+					identifier: "string",
+					maximum_length: 10,
+				},
+				{
+					type: "string",
+					label: "String field",
+					required: true,
+					identifier: "another_string",
+					minimum_length: 2,
+					maximum_length: 10,
+				},
+			],
+		},
+	],
+}
+const schema = formRevisionToSchema(partialFormRevision)
+const values = { string: "string", another_string: "another" }
+
+const meta = {
+	title: "Renderer/PatchForm",
+	component: PatchFormProvider,
+	tags: ["autodocs"],
+	args: {
+		values,
+		schema,
+	},
+} satisfies Meta<typeof PatchFormProvider>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Use the `Actions` tab to see when the `onError` or `onPatch` events fire. */
+export const Basic: Story["render"] = (props) => {
+	return (
+		<PatchFormProvider {...props}>
+			<div className="flex flex-col gap-2">
+				<label className="flex gap-1">
+					string
+					<PatchField
+						name="string"
+						render={(props) => (
+							<input
+								value={props.value as string}
+								onChange={(e) => {
+									props.setValue(e.target.value)
+								}}
+								onBlur={props.patchValue}
+							/>
+						)}
+					/>
+				</label>
+				<label className="flex gap-1">
+					another_string
+					<PatchField
+						name="another_string"
+						render={(props) => (
+							<input
+								value={props.value as string}
+								onChange={(e) => {
+									props.setValue(e.target.value)
+								}}
+								onBlur={props.patchValue}
+							/>
+						)}
+					/>
+				</label>
+			</div>
+		</PatchFormProvider>
+	)
+}

package/src/forms/renderer/PatchForm/Provider.tsx

@@ -0,0 +1,119 @@
+import { FormikErrors, FormikProvider, useFormik } from "formik"
+import { FormEventHandler, forwardRef, memo, useCallback, useEffect, useMemo } from "react"
+
+import { NewForm } from "../../builder"
+import { ISchema } from "../../fields"
+import { Form } from "../../typings"
+import { hasKeys, initialFormValues, validateForm } from "../../utils"
+
+interface PatchFormProviderProps {
+	children: React.ReactNode
+	schema: ISchema
+	values: Form
+	/** Called when `patchValue` is called on a child `PatchField` and the form is valid.
+	 *  @example ```js
+	 * {"field name": "field value"}
+	 * ``` */
+	onPatch: (values: Form) => void
+	/** Called when `patchValue` is called on a child `PatchField` and the form is not valid.
+	 * After this event is fired, the form is reset to the initial values.
+	 * @example ```js
+	 * {"field name": "error message"}
+	 * ``` */
+	onError: (error: FormikErrors<Form | NewForm>) => void
+	className?: string
+	/** If true (default), the form will only submit if there are changes. */
+	requiresDiff?: boolean
+	/** Called when the form's dirty state changes. */
+	onDirtyChange?: (dirty: boolean) => void
+}
+
+/** Use PatchForms to create patch edits to existing forms rather than editing the entire form. */
+export const PatchFormProvider = memo(
+	forwardRef<HTMLFormElement, PatchFormProviderProps>((props, ref) => {
+		const { children, schema, values, onPatch, onError, requiresDiff = true, onDirtyChange, ...rest } = props
+
+		const initialValues = useMemo(() => initialFormValues(schema.fields, values), [schema.fields, values])
+
+		const getDiff = useCallback(
+			(values: Form): Form => {
+				const diff: Form = {}
+
+				for (const key in values) {
+					const value = values[key]
+					if (value !== initialValues[key] && value !== undefined) {
+						diff[key] = value
+					}
+				}
+
+				return diff
+			},
+			[initialValues],
+		)
+
+		const handlePatch = useCallback(
+			(values: Form) => {
+				const diff: Form = getDiff(values)
+				// skip if no changes
+				if (requiresDiff && !hasKeys(diff)) return
+				onPatch(diff)
+			},
+			[getDiff, onPatch, requiresDiff],
+		)
+
+		const validate = useCallback(
+			(form: Form) => {
+				const error = validateForm(schema, form)
+
+				if (error) {
+					// report the error
+					onError(error)
+				}
+
+				if (onDirtyChange) {
+					const diff = getDiff(form)
+					onDirtyChange(hasKeys(diff))
+				}
+
+				return error
+			},
+			[schema, onDirtyChange, onError, getDiff],
+		)
+
+		const formik = useFormik<Form>({
+			initialValues,
+			onSubmit: handlePatch,
+			validate,
+			// only validate the entire form on submit
+			validateOnBlur: false,
+			validateOnChange: false,
+		})
+
+		const handleChange: FormEventHandler<HTMLFormElement> = useCallback(() => {
+			if (onDirtyChange) {
+				const diff = getDiff(formik.values)
+				if (hasKeys(diff)) {
+					onDirtyChange(true)
+				}
+			}
+		}, [formik.values, getDiff, onDirtyChange])
+
+		const { errors, resetForm } = formik
+
+		useEffect(() => {
+			// on errors, reset the form the initial values
+			if (hasKeys(errors)) {
+				resetForm({ values: initialValues, errors: {} })
+			}
+		}, [errors, initialValues, resetForm])
+
+		return (
+			<FormikProvider value={formik}>
+				{/* the `form` captures any submit events that are generated */}
+				<form {...rest} ref={ref} onSubmit={formik.handleSubmit} onChange={handleChange}>
+					{children}
+				</form>
+			</FormikProvider>
+		)
+	}),
+)

package/src/forms/renderer/PatchForm/index.ts

@@ -0,0 +1,2 @@
+export * from "./Field"
+export * from "./Provider"

package/src/forms/renderer/index.ts

@@ -0,0 +1,2 @@
+export * from "./FormRenderer/FormRenderer"
+export * from "./PatchForm"

package/src/forms/typings.ts

@@ -0,0 +1,162 @@
+import { Marker } from "@overmap-ai/core"
+import { HTMLInputTypeAttribute } from "react"
+
+import { AnyField, BaseField } from "./fields"
+
+/**
+ * When upload fields are given initial values, that value will be
+ * a `Promise<File>[]` instead of a `File[]` as the files must be downloaded.
+ * `Promise<File>[]` is not add to the `FieldValue` type as it is not a valid
+ * value for submitted forms as the files must be present to be submitted
+ * TODO: This causes type errors in hemora-web. Maybe we should change this to:
+ *  export type Form = {
+ *    data: Record<string, FieldValue>,
+ *    attachments: Record<string, Promise<File>[]>
+ *  }
+ *  Then, we could just use `data` for creating attachment instances.
+ */
+export type Form = Record<string, FieldValue | Promise<File>[]>
+
+/** Helper type that extracts the TValue type from a BaseField. */
+export type ValueOfField<Type extends AnyField> = Type extends BaseField<infer TValue> ? TValue : never
+
+// Register all allowed field types here.
+// Note: a serialized type does not exist for custom, as it is only used for internal forms
+export type FieldTypeIdentifier =
+	| "string"
+	| "text"
+	| "boolean"
+	| "number"
+	| "date"
+	| "select"
+	| "custom"
+	| "section"
+	| "multi-string"
+	| "multi-select"
+	| "upload"
+	| "qr"
+
+export interface BaseSerializedObject<TIdentifier extends FieldTypeIdentifier = FieldTypeIdentifier> {
+	description?: string | null
+	identifier: string
+	type: TIdentifier
+}
+
+export interface BaseSerializedField<TIdentifier extends FieldTypeIdentifier = FieldTypeIdentifier>
+	extends BaseSerializedObject<TIdentifier> {
+	label: string
+	required: boolean
+	image?: File | Promise<File>
+}
+
+/** All the possible field values */
+export type FieldValue = string | number | boolean | string[] | File[] | Date | Marker | null
+
+export interface SerializedCondition<TValue extends FieldValue = FieldValue> {
+	identifier: string
+	// multi-string fields would produce an array of `SelectFieldOption`
+	value: TValue
+}
+
+export interface SerializedFieldSection extends BaseSerializedObject {
+	label: string | null
+	type: "section"
+	conditional: boolean
+	condition: SerializedCondition | null
+	fields: Exclude<ISerializedField, SerializedFieldSection>[]
+}
+
+interface BaseSerializedStringField extends BaseSerializedField {
+	minimum_length?: number
+	maximum_length: number
+	placeholder?: string
+}
+
+export type StringInputType = Exclude<HTMLInputTypeAttribute, "checkbox" | "number" | "button">
+
+export interface SerializedStringField extends BaseSerializedStringField {
+	type: "string"
+	input_type?: StringInputType
+}
+
+export interface SerializedQrField extends BaseSerializedField {
+	type: "qr"
+}
+
+export interface SerializedTextField extends BaseSerializedStringField {
+	type: "text"
+}
+
+export interface SerializedMultiStringField extends BaseSerializedStringField {
+	type: "multi-string"
+}
+
+export interface SerializedBooleanField extends BaseSerializedField {
+	type: "boolean"
+	// TODO:
+	// default?: boolean
+}
+
+export interface SerializedNumberField extends BaseSerializedField {
+	type: "number"
+	minimum: number | undefined
+	maximum: number | undefined
+	integers: boolean
+	placeholder?: string
+}
+
+export interface SerializedDateField extends BaseSerializedField {
+	type: "date"
+}
+
+// The types of values that can be selected in the select input.
+export type SelectFieldOptionValue = string
+
+/** Represents an option in the select input. Not to be confused with the 'field options' of SelectField. */
+export interface SelectFieldOption {
+	value: SelectFieldOptionValue
+	label: string
+}
+
+export interface SerializedSelectField extends BaseSerializedField {
+	type: "select"
+	options: SelectFieldOption[]
+	placeholder?: string
+}
+
+export interface SerializedMultiSelectField extends BaseSerializedField {
+	type: "multi-select"
+	options: SelectFieldOption[]
+	placeholder?: string
+}
+
+export interface SerializedUploadField extends BaseSerializedField {
+	type: "upload"
+	/** @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept */
+	extensions?: string[]
+	/** in bytes */
+	maximum_size?: number
+	/** how many files the user can upload to this field
+	 * @default 1
+	 */
+	maximum_files?: number
+}
+
+export type ISerializedField =
+	// Add type hints for final field interfaces
+	| SerializedTextField
+	| SerializedBooleanField
+	| SerializedNumberField
+	| SerializedDateField
+	| SerializedStringField
+	| SerializedSelectField
+	| SerializedFieldSection
+	| SerializedMultiStringField
+	| SerializedMultiSelectField
+	| SerializedUploadField
+	| SerializedQrField
+
+// REASON: Sometimes, we don't accept a FieldSection
+export type ISerializedOnlyField = Exclude<ISerializedField, SerializedFieldSection>
+
+export type Severity = "danger" | "warning" | "info" | "success"