@overmap-ai/forms 1.0.15 → 1.0.17-master.0

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">

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"