@overmap-ai/forms 0.0.1-master.3

package/src/forms/fields/BooleanField/BooleanField.tsx

@@ -0,0 +1,48 @@
+import { ChangeEvent, ReactNode } from "react"
+import { RiCheckboxCircleLine } from "react-icons/ri"
+
+import { ISerializedField, SerializedBooleanField } from "../../typings"
+import { BaseField, ChildFieldOptions, emptyBaseField } from "../BaseField"
+import { ComponentProps } from "../typings"
+import { BooleanInput } from "./BooleanInput"
+
+export const emptyBooleanField = {
+	...emptyBaseField,
+	type: "boolean",
+}
+
+export class BooleanField extends BaseField<boolean, "boolean"> {
+	static readonly fieldTypeName = "Checkbox"
+	static readonly fieldTypeDescription = "Perfect for both optional and required yes/no questions."
+
+	public readonly onlyValidateAfterTouched = false
+
+	static Icon: typeof RiCheckboxCircleLine = RiCheckboxCircleLine
+
+	public constructor(options: ChildFieldOptions<boolean>) {
+		super({ ...options, type: "boolean" })
+	}
+
+	// if a BooleanField is required, `false` is considered blank
+	protected isBlank(value: boolean): boolean {
+		return this.required && !value
+	}
+
+	public getValueFromChangeEvent(event: ChangeEvent<HTMLInputElement> | boolean): boolean {
+		if (typeof event === "boolean") return event
+		return event.target.checked
+	}
+
+	serialize(): SerializedBooleanField {
+		return super._serialize()
+	}
+
+	static deserialize(data: ISerializedField): BooleanField {
+		if (data.type !== "boolean") throw new Error("Type mismatch.")
+		return new BooleanField(data)
+	}
+
+	getInput(props: ComponentProps<BooleanField>): ReactNode {
+		return <BooleanInput {...props} field={this} />
+	}
+}

package/src/forms/fields/BooleanField/BooleanInput.tsx

@@ -0,0 +1,54 @@
+import { Checkbox, RiIcon } from "@overmap-ai/blocks"
+import { memo } from "react"
+
+import { SEVERITY_COLOR_MAPPING } from "../../constants"
+import { InputWithLabel, InputWithLabelAndHelpText } from "../BaseField"
+import { useFormikInput } from "../BaseField"
+import { ComponentProps } from "../typings"
+import { BooleanField } from "./BooleanField"
+
+const truthyValues = [true, "true"]
+
+export const BooleanInput = memo((props: ComponentProps<BooleanField>) => {
+	const [{ inputId, labelId, size, severity, showInputOnly, field, fieldProps }, rest] = useFormikInput(props)
+	let [{ helpText, label }] = useFormikInput(props)
+	helpText = showInputOnly ? null : helpText
+	label = showInputOnly ? "" : label
+
+	const color = severity ? SEVERITY_COLOR_MAPPING[severity] : undefined
+	const value = truthyValues.includes(fieldProps.value)
+
+	return (
+		<InputWithLabelAndHelpText helpText={helpText} severity={severity}>
+			<InputWithLabel
+				size={size}
+				severity={severity}
+				inputId={inputId}
+				labelId={labelId}
+				label={label}
+				image={showInputOnly ? undefined : field.image}
+				className="align-center flex-row-reverse justify-end gap-2"
+			>
+				<Checkbox.Root
+					{...rest}
+					{...fieldProps}
+					id={inputId}
+					accentColor={color}
+					value={value.toString()}
+					checked={value}
+					onCheckedChange={fieldProps.onChange}
+					// disabled onChange and onBlur as that is handled by onCheckedChange
+					onChange={undefined}
+					onBlur={undefined}
+					variant="soft"
+				>
+					<Checkbox.Indicator>
+						<RiIcon icon="RiCheckLine" />
+					</Checkbox.Indicator>
+				</Checkbox.Root>
+			</InputWithLabel>
+		</InputWithLabelAndHelpText>
+	)
+})
+
+BooleanInput.displayName = "BooleanInput"

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

@@ -0,0 +1,2 @@
+export * from "./BooleanField"
+export * from "./BooleanInput"

package/src/forms/fields/CustomField/CustomField.tsx

@@ -0,0 +1,45 @@
+import { ISerializedOnlyField } from "@overmap-ai/core"
+import { FC, ReactNode } from "react"
+
+import { FieldTypeIdentifier, FieldValue } from "../../typings"
+import { BaseField, ChildFieldOptions, emptyBaseField } from "../BaseField"
+import { GetInputProps } from "../typings"
+
+export type CustomFieldOptions<TValue> = ChildFieldOptions<TValue>
+
+export const emptyCustomField = {
+	...emptyBaseField,
+	type: "custom",
+}
+
+export class CustomField<
+	TValue extends FieldValue,
+	/** The options passed to constructor */
+	TFieldOptions extends CustomFieldOptions<TValue>,
+	/** The props passed to the custom component */
+	TComponentProps extends GetInputProps<CustomField<TValue, TFieldOptions, TComponentProps>>,
+	TIdentifier extends FieldTypeIdentifier = FieldTypeIdentifier,
+> extends BaseField<TValue, TIdentifier> {
+	static readonly fieldTypeName = "Custom"
+	static readonly fieldTypeDescription = "Allows re-rendering of field already in the form"
+
+	public readonly Component: FC<TComponentProps>
+
+	// identifier of the field whose value is the label of the field to re-render
+	public readonly options: TFieldOptions
+
+	constructor(options: TFieldOptions, Component: FC<TComponentProps>) {
+		super({ ...options, type: "custom" })
+		this.options = options
+		this.Component = Component
+	}
+
+	serialize(): ISerializedOnlyField {
+		throw new Error("Serializing only supported for public input types.")
+	}
+
+	getInput(props: TComponentProps): ReactNode {
+		const CustomInput = this.Component
+		return <CustomInput field={this} {...props} />
+	}
+}

package/src/forms/fields/CustomField/FieldInputClonerField/FieldInputCloner.tsx

@@ -0,0 +1,25 @@
+import { useField } from "formik"
+import { memo, useMemo } from "react"
+
+import { deserialize, useFieldInput } from "../../index"
+import { FieldInputClonerProps } from "./typings"
+
+/**
+ * Used to dynamically "clone" a field's input for use in conditional sections. When a field is selected for a
+ * condition, we need to render the same input in the condition section, so the user can input a value for the
+ * condition.
+ */
+export const FieldInputCloner = memo((props: FieldInputClonerProps) => {
+	const { field, ...rest } = props
+	const [{ value: identifier }] = useField<string>(field.options.clonedFieldIdentifier)
+
+	const deserializedField = useMemo(() => {
+		const options = field.options.getFieldToClone(identifier)
+		if (!options) return null
+		return deserialize(options)
+	}, [field.options, identifier])
+
+	return useFieldInput(deserializedField, rest)
+})
+
+FieldInputCloner.displayName = "FieldInputCloner"

package/src/forms/fields/CustomField/FieldInputClonerField/FieldInputClonerField.tsx

@@ -0,0 +1,26 @@
+import { FieldValue, ISerializedField } from "../../../typings"
+import { CustomField, CustomFieldOptions } from "../CustomField"
+import { FieldInputCloner, FieldInputClonerProps } from "./index"
+
+export interface FieldInputClonerFieldOptions extends CustomFieldOptions<unknown> {
+	/** Given an identifier, should return the options of the field with the
+	 * corresponding identifier (the field being cloned) */
+	getFieldToClone: (identifier: string) => ISerializedField | null
+	/** The identifier of the field to clone */
+	clonedFieldIdentifier: string
+}
+
+/**
+ * The purpose of this is to display a value input field in the condition of a section. The input field will look like
+ * the input field of the condition. For example, when specifying the conditional value of a SelectField, a SelectInput
+ * will be rendered.
+ */
+export class FieldInputClonerField extends CustomField<
+	FieldValue,
+	FieldInputClonerFieldOptions,
+	FieldInputClonerProps
+> {
+	constructor(options: FieldInputClonerFieldOptions) {
+		super(options, FieldInputCloner)
+	}
+}

package/src/forms/fields/CustomField/FieldInputClonerField/index.ts

@@ -0,0 +1,3 @@
+export * from "./FieldInputCloner"
+export * from "./FieldInputClonerField"
+export * from "./typings"

package/src/forms/fields/CustomField/FieldInputClonerField/typings.ts

@@ -0,0 +1,8 @@
+import { FieldValue } from "../../../typings"
+import { AnyField, ComponentProps, GetInputProps } from "../../typings"
+import { CustomField } from "../CustomField"
+import { FieldInputClonerFieldOptions } from "./FieldInputClonerField"
+
+export type FieldInputClonerProps = ComponentProps<
+	CustomField<FieldValue, FieldInputClonerFieldOptions, GetInputProps<AnyField>>
+>

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

@@ -0,0 +1 @@
+export * from "./CustomField"

package/src/forms/fields/DateField/DateField.tsx

@@ -0,0 +1,42 @@
+import { ChangeEvent, ReactNode } from "react"
+import { RiCalendarLine } from "react-icons/ri"
+
+import { ISerializedField, SerializedDateField } from "../../typings"
+import { BaseField, ChildFieldOptions, emptyBaseField } from "../BaseField"
+import { GetInputProps } from "../typings"
+import { DateInput } from "./DateInput"
+
+export const emptyDateField = {
+	...emptyBaseField,
+	type: "date",
+}
+
+export class DateField extends BaseField<string, "date"> {
+	static readonly fieldTypeName = "Date"
+	static readonly fieldTypeDescription = "Allows specifying a date."
+
+	static Icon: typeof RiCalendarLine = RiCalendarLine
+
+	public readonly onlyValidateAfterTouched = false
+
+	public constructor(options: ChildFieldOptions<string>) {
+		super({ ...options, type: "date" })
+	}
+
+	serialize(): SerializedDateField {
+		return super._serialize()
+	}
+
+	public getValueFromChangeEvent(event: ChangeEvent<HTMLInputElement>): string {
+		return new Date(event.target.value).toISOString()
+	}
+
+	static deserialize(data: ISerializedField): DateField {
+		if (data.type !== "date") throw new Error("Type mismatch.")
+		return new DateField(data)
+	}
+
+	getInput(props: GetInputProps<this>): ReactNode {
+		return <DateInput field={this} {...props} />
+	}
+}

package/src/forms/fields/DateField/DateInput.tsx

@@ -0,0 +1,39 @@
+import { Input } from "@overmap-ai/blocks"
+import { memo } from "react"
+
+import { SEVERITY_COLOR_MAPPING } from "../../constants"
+import { InputWithLabel, InputWithLabelAndHelpText, useFormikInput } from "../BaseField"
+import { ComponentProps } from "../typings"
+import { DateField } from "./DateField"
+
+export const DateInput = memo((props: ComponentProps<DateField>) => {
+	const [{ inputId, labelId, size, severity, showInputOnly, field, fieldProps }, rest] = useFormikInput(props)
+	let [{ helpText, label }] = useFormikInput(props)
+	helpText = showInputOnly ? null : helpText
+	label = showInputOnly ? "" : label
+
+	const color = severity ? SEVERITY_COLOR_MAPPING[severity] : undefined
+
+	// TODO: Add timezone info
+	// remove the time from the date
+	const value: string = fieldProps.value ? fieldProps.value.split("T")[0]! : ""
+
+	return (
+		<InputWithLabelAndHelpText helpText={helpText} severity={severity}>
+			<InputWithLabel
+				size={size}
+				severity={severity}
+				inputId={inputId}
+				labelId={labelId}
+				label={label}
+				image={showInputOnly ? undefined : field.image}
+			>
+				<Input.Root accentColor={color} variant="soft">
+					<Input.Field {...rest} type="date" id={inputId} color={color} value={value} />
+				</Input.Root>
+			</InputWithLabel>
+		</InputWithLabelAndHelpText>
+	)
+})
+
+DateInput.displayName = "DateInput"

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

@@ -0,0 +1,2 @@
+export * from "./DateField"
+export * from "./DateInput"

package/src/forms/fields/FieldSection/FieldSection.tsx

@@ -0,0 +1,173 @@
+import get from "lodash.get"
+import set from "lodash.set"
+import { ReactNode } from "react"
+
+import { FormikUserFormRevision } from "../../builder"
+import {
+	BaseSerializedObject,
+	Form,
+	ISerializedField,
+	SelectFieldOption,
+	SerializedCondition,
+	SerializedFieldSection,
+} from "../../typings"
+import { FieldInputClonerField, FieldInputClonerFieldOptions } from "../CustomField/FieldInputClonerField"
+import { AnyField, BaseFormElement, BooleanField, deserializeField, GetInputProps, SelectField } from "../index"
+import { FieldSectionLayout } from "./FieldSectionLayout"
+
+interface FieldSectionOptions extends Omit<BaseSerializedObject, "type"> {
+	label?: string | null
+	conditional?: boolean
+	condition?: SerializedCondition | null
+	fields: AnyField[]
+}
+
+export class FieldSection extends BaseFormElement<"section"> {
+	static readonly fieldTypeName = "Section"
+	static readonly fieldTypeDescription =
+		"Sections can be useful for grouping fields together. They can also be conditionally shown or hidden."
+
+	public readonly label: string | null
+	public readonly fields: AnyField[]
+	public readonly condition: SerializedCondition | null
+
+	public constructor(options: FieldSectionOptions) {
+		const { label = null, fields, condition = null, conditional, ...base } = options
+
+		super({ ...base, type: "section" })
+		this.fields = fields
+		this.condition = condition
+		this.label = label
+
+		// handle case when condition is removed
+		if (conditional === false) {
+			this.condition = null
+		}
+	}
+
+	static getFieldCreationSchema(options: ISerializedField[], parentPath = "") {
+		// conditions require at least one field to be present
+		if (options.length === 0) return []
+
+		const path = parentPath && `${parentPath}.`
+		return [
+			{
+				field: new BooleanField({
+					label: "Conditionally render section",
+					identifier: `${path}conditional`,
+					required: false,
+				}),
+				showDirectly: true,
+			},
+			{
+				// Declare a section that will hold options for the condition (if any).
+				field: new FieldSection({
+					label: "Conditional settings",
+					identifier: `${path}conditional-settings`,
+					// This section will only be rendered if the above "Conditional" field is checked.
+					condition: {
+						identifier: `${path}conditional`,
+						value: true,
+					},
+					// These are the options of the condition.
+					fields: [
+						// Declare a select field that will be used to select the field against which we will check the
+						// condition. This must be selected before the next field is rendered.
+						new SelectField({
+							label: "Field",
+							description: "The field to use for the condition.",
+							// The options (for the field against which we will check the condition) are all the labels of
+							// the fields in the previous section(s) (or fields declared before with no section) that
+							// support conditions. We pass in both the label and the identifier of each supported field. The
+							// identifier becomes the value of the option.
+							options: options
+								.map((option): SelectFieldOption | null => {
+									// If the field doesn't have a label, it can't be used for a condition.
+									if (!option.label) return null
+									// Upload fields cannot be used for conditions.
+									if (option.type === "upload") return null
+
+									return {
+										label: option.label,
+										value: option.identifier,
+									}
+								})
+								.filter((option): option is SelectFieldOption => !!option),
+							identifier: `${path}condition.identifier`,
+							required: true,
+						}),
+						// Declare a custom field that will be used to input a value for the condition. The value of the
+						// conditional field selected in the previous step must be equal to the value the user inputs into
+						// this field for the section to be rendered.
+						new FieldInputClonerField({
+							label: "Value",
+							identifier: `${path}condition.value`,
+							required: true,
+							clonedFieldIdentifier: `${path}condition.identifier`,
+							getFieldToClone(identifier: string) {
+								if (!identifier) {
+									// No field has been chosen yet.
+									return null
+								}
+								// Find the field options with a matching identifier.
+								const option = options.find((option) => option.identifier === identifier)
+								if (!option) {
+									console.error("Could not find field with identifier", identifier)
+									return null
+								}
+								return {
+									...option,
+									// Override some options to make it make sense in the context and to make it work with the framework.
+									label: "Value",
+									identifier: `${path}condition.value`,
+									description: "The value to compare against.",
+									required: option.type !== "boolean",
+								}
+							},
+						} satisfies FieldInputClonerFieldOptions),
+					],
+				}),
+				showDirectly: false,
+			},
+		]
+	}
+
+	static deserialize(data: ISerializedField): FieldSection {
+		if (data.type !== "section") throw new Error("Invalid type")
+		// REASON: Handling an edge case
+
+		if (!Array.isArray(data.fields)) throw new Error(`Invalid fields: ${data.fields} (not an array)`)
+		const fields = data.fields.map(deserializeField)
+		return new FieldSection({ ...data, fields })
+	}
+
+	conditional(): this is { condition: SerializedCondition } {
+		return this.condition !== null
+	}
+
+	serialize(): SerializedFieldSection {
+		return {
+			...super._serialize(),
+			label: this.label,
+			condition: this.condition,
+			conditional: this.conditional(),
+			fields: this.fields.map((field) => field.serialize()),
+		}
+	}
+
+	getErrors(allValues: Form | FormikUserFormRevision): Record<string, string> {
+		const errors: Record<string, string> = {}
+		for (const field of this.fields) {
+			const id = field.getId()
+			const error = field.getError(get(allValues, id), allValues)
+			if (error) {
+				set(errors, field.getId(), error)
+			}
+		}
+		return errors
+	}
+
+	getInput(props: GetInputProps<this>): ReactNode {
+		return <FieldSectionLayout field={this} {...props} />
+	}
+}

package/src/forms/fields/FieldSection/FieldSectionLayout.tsx

@@ -0,0 +1,56 @@
+import { Card, Heading, Text } from "@overmap-ai/blocks"
+import { useFormikContext } from "formik"
+import get from "lodash.get"
+import { memo, useEffect, useMemo } from "react"
+
+import { FieldValue } from "../../typings"
+import { useFieldInputs } from "../hooks"
+import { ComponentProps } from "../typings"
+import { isConditionMet } from "../utils"
+import { FieldSection } from "./FieldSection"
+
+/**
+ * Used by FieldSection to render a section of fields.
+ */
+export const FieldSectionLayout = memo((props: ComponentProps<FieldSection>) => {
+	const { field: section, ...rest } = props
+	const { label, description, fields, condition } = section
+	const { values, setFieldValue } = useFormikContext()
+
+	const conditionValue = condition?.identifier ? (get(values, condition.identifier) as FieldValue) : undefined
+	// sections without a condition are always met
+	const conditionMet = useMemo(
+		() => conditionValue === undefined || isConditionMet(condition, conditionValue),
+		[condition, conditionValue],
+	)
+
+	useEffect(() => {
+		// reset all fields in section if condition is not met
+		if (!conditionMet) {
+			for (const childField of fields) {
+				void setFieldValue(childField.getId(), "").then()
+			}
+		}
+	}, [conditionMet, fields, setFieldValue])
+
+	const inputs = useFieldInputs(fields, rest)
+
+	// if condition is not met, do not render section
+	if (!conditionMet) {
+		return null
+	}
+
+	return (
+		<Card>
+			<div className="flex flex-col gap-6">
+				<div className="flex flex-col">
+					<Heading size="lg">{label}</Heading>
+					<Text accentColor="base">{description}</Text>
+				</div>
+				{inputs}
+			</div>
+		</Card>
+	)
+})
+
+FieldSectionLayout.displayName = "FieldSectionLayout"

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

@@ -0,0 +1 @@
+export * from "./FieldSection"

package/src/forms/fields/MultiStringField/MultiStringField.tsx

@@ -0,0 +1,90 @@
+import { ChangeEvent, ReactNode } from "react"
+import { RiListCheck } from "react-icons/ri"
+
+import { ISerializedField, SerializedMultiStringField } from "../../typings"
+import { BaseField, ChildFieldOptions, emptyBaseField } from "../BaseField"
+import { GetInputProps, InputFieldLevelValidator } from "../typings"
+import { MultiStringInput } from "./MultiStringInput"
+
+type MultiStringFieldOptions = ChildFieldOptions<string[]> & {
+	minimum_length?: number
+	maximum_length?: number
+	placeholder?: string
+}
+
+export const emptyMultiStringField = {
+	...emptyBaseField,
+	type: "multi-string",
+	minimum_length: 0,
+	maximum_length: null,
+}
+
+/**
+ * A field that lets the user input multiple strings. Each string must be unique. Useful for things like:
+ * - Specifying the options of a SelectField (used in `SelectField.getFieldCreationSchema`
+ * - Listing serial numbers and similar
+ */
+export class MultiStringField extends BaseField<string[], "multi-string"> {
+	static readonly fieldTypeName = "Multi-string"
+	static readonly fieldTypeDescription = "Allows the user to provide multiple unique strings."
+	public readonly minLength: number
+	public readonly maxLength: number
+	public readonly onlyValidateAfterTouched = false
+	public readonly placeholder: string
+
+	static Icon: typeof RiListCheck = RiListCheck
+
+	constructor(options: MultiStringFieldOptions) {
+		const { minimum_length, maximum_length, placeholder, ...rest } = options
+		super({ ...rest, type: "multi-string" })
+		this.minLength = minimum_length ?? 0
+		this.maxLength = maximum_length ?? Infinity
+		this.placeholder = placeholder ?? "Press enter to add a new option"
+	}
+
+	public getValueFromChangeEvent(event: ChangeEvent<HTMLInputElement> | string[]): string[] {
+		if (Array.isArray(event)) return event
+
+		throw new Error("Expected an array.")
+	}
+
+	getInput(props: GetInputProps<this>): ReactNode {
+		return <MultiStringInput field={this} {...props} />
+	}
+
+	serialize(): SerializedMultiStringField {
+		return {
+			...super._serialize(),
+			minimum_length: this.minLength,
+			maximum_length: this.maxLength,
+			placeholder: this.placeholder,
+		}
+	}
+
+	protected isBlank(value: string[]): boolean {
+		return super.isBlank(value) || value.length === 0
+	}
+
+	public getFieldValidators(): InputFieldLevelValidator<string[]>[] {
+		const validators = super.getFieldValidators()
+
+		validators.push((value) => {
+			if (Array.isArray(value) && value.length < this.minLength) {
+				return `Must have at least ${this.minLength} options.`
+			}
+		})
+
+		validators.push((value) => {
+			if (Array.isArray(value) && value.length > this.maxLength) {
+				return `Must have at most ${this.maxLength} options.`
+			}
+		})
+
+		return validators
+	}
+
+	static deserialize(data: ISerializedField): MultiStringField {
+		if (data.type !== "multi-string") throw new Error("Type mismatch.")
+		return new MultiStringField(data)
+	}
+}