@overmap-ai/forms 0.0.1-master.3

package/src/forms/fields/UploadField/UploadField.tsx

@@ -0,0 +1,156 @@
+import { ChangeEvent, ReactNode } from "react"
+import { RiUpload2Line } from "react-icons/ri"
+
+import { ISerializedField, SerializedUploadField } from "../../typings"
+import { BaseField, ChildFieldOptions, emptyBaseField } from "../BaseField"
+import { maxFileSizeMB } from "../constants"
+import { NumberField } from "../NumberField"
+import { MultiSelectField } from "../SelectField"
+import { GetInputProps, InputFieldLevelValidator } from "../typings"
+import { UploadInput } from "./UploadInput"
+
+export interface UploadFieldOptions extends ChildFieldOptions<File[]> {
+	extensions?: string[]
+	maximum_size?: number | string
+	maximum_files?: number | string
+}
+
+export const emptyUploadField = {
+	...emptyBaseField,
+	type: "upload",
+	extensions: [],
+	maximum_size: undefined,
+	maximum_files: 1,
+}
+
+export class UploadField extends BaseField<File[], "upload"> {
+	static readonly fieldTypeName = "Upload"
+	static readonly fieldTypeDescription = "Allows a file to be uploaded."
+
+	public readonly extensions?: string[]
+	public readonly maxFileSize: number | undefined
+	public readonly maxFiles: number
+	public readonly onlyValidateAfterTouched = false
+
+	static Icon: typeof RiUpload2Line = RiUpload2Line
+
+	constructor(options: UploadFieldOptions) {
+		const { extensions, maximum_files, maximum_size, ...base } = options
+		super({ ...base, type: "upload" })
+
+		this.maxFileSize = typeof maximum_size === "number" ? maximum_size : undefined
+		// if maximum_files is not a number or less than 1, default and clamp to 1
+		this.maxFiles = Math.max(typeof maximum_files === "number" ? maximum_files : 1, 1)
+
+		this.extensions = extensions
+	}
+
+	public getValueFromChangeEvent(event: ChangeEvent<HTMLInputElement>): File[] {
+		return Array.from(event.target.files || [])
+	}
+
+	protected isBlank(value: File[]): boolean {
+		return super.isBlank(value) || value.length === 0
+	}
+
+	static getFieldCreationSchema(parentPath = "") {
+		const path = parentPath && `${parentPath}.`
+		return [
+			{
+				field: new NumberField({
+					label: "How many files can be uploaded?",
+					description: "By default, only one file can be uploaded.",
+					required: false,
+					minimum: 1,
+					maximum: 10,
+					identifier: `${path}maximum_files`,
+					integers: true,
+				}),
+				showDirectly: false,
+			},
+			{
+				field: new NumberField({
+					// TODO: Default value
+					label: "What is the maximum size of each file?",
+					description: `Maximum file size in megabytes (between 1MB–${maxFileSizeMB}MB).`,
+					required: false,
+					identifier: `${path}maximum_size`,
+					minimum: 1,
+					maximum: maxFileSizeMB,
+					integers: true,
+				}),
+				showDirectly: false,
+			},
+			{
+				field: new MultiSelectField({
+					label: "Accepted file types",
+					description: "Types of allowed files to upload. If left blank, all files will be accepted.",
+					required: false,
+					identifier: `${path}extensions`,
+					options: [
+						{
+							value: "image/*",
+							label: "Images",
+						},
+						{
+							value: "audio/*",
+							label: "Audio files",
+						},
+						{
+							value: "video/*",
+							label: "Videos",
+						},
+						{
+							value: "text/*",
+							label: "Text files",
+						},
+						{
+							value: "application/*",
+							label: "Application files (includes PDFs and Word documents)",
+						},
+					],
+				}),
+				showDirectly: false,
+			},
+		]
+	}
+
+	getFieldValidators(): InputFieldLevelValidator<File[]>[] {
+		const validators = super.getFieldValidators()
+		const maxFileSizeInMB = this.maxFileSize ?? maxFileSizeMB
+		const maxFileSizeInB = maxFileSizeInMB * 1000 * 1000
+		const maxFiles = this.maxFiles || 1
+
+		validators.push((value) => {
+			if (value && value.some((file) => file.size > maxFileSizeInB)) {
+				return `Files must be at most ${maxFileSizeInMB}MB.`
+			}
+		})
+
+		validators.push((value) => {
+			if (value && value.length > maxFiles) {
+				return `You can only upload ${maxFiles} files.`
+			}
+		})
+
+		return validators
+	}
+
+	serialize(): SerializedUploadField {
+		return {
+			...super._serialize(),
+			extensions: this.extensions,
+			maximum_size: this.maxFileSize,
+			maximum_files: this.maxFiles,
+		}
+	}
+
+	static deserialize(data: ISerializedField): UploadField {
+		if (data.type !== "upload") throw new Error("Type mismatch.")
+		return new UploadField(data)
+	}
+
+	getInput(props: GetInputProps<this>): ReactNode {
+		return <UploadInput field={this} {...props} />
+	}
+}

package/src/forms/fields/UploadField/UploadInput.tsx

@@ -0,0 +1,220 @@
+import { Button, ButtonGroup, IconButton, RiIcon } from "@overmap-ai/blocks"
+import { saveAs } from "file-saver"
+import { memo, MouseEvent, ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react"
+
+import { FileCard } from "../../../FileCard"
+import { useFileViewer } from "../../../FileViewer"
+import { ImageCard } from "../../../ImageCard"
+import { SEVERITY_COLOR_MAPPING } from "../../constants"
+import { InputWithLabel, InputWithLabelAndHelpText, useFormikInput } from "../BaseField"
+import { ComponentProps } from "../typings"
+import { UploadField } from "./UploadField"
+import { convertBytesToLargestUnit } from "./utils"
+
+export const UploadInput = memo((props: ComponentProps<UploadField>) => {
+	const [{ inputId, labelId, size, severity, helpText, showInputOnly, field, fieldProps }, rest] =
+		useFormikInput(props)
+	const { onChange } = fieldProps
+	let [{ label }] = useFormikInput(props)
+	label = showInputOnly ? "" : label
+
+	const color = severity ? SEVERITY_COLOR_MAPPING[severity] : undefined
+	const input = useRef<HTMLInputElement>(null)
+	const { value } = fieldProps
+
+	const updatedHelpText = useMemo(() => {
+		if (showInputOnly) return null
+		if (helpText) return helpText
+		if (field.maxFileSize) {
+			return `Maximum file size: ${field.maxFileSize}MB`
+		}
+		return null
+	}, [field.maxFileSize, helpText, showInputOnly])
+
+	const handleClick = useCallback(() => {
+		input.current?.click()
+	}, [])
+
+	const handleRemove = useCallback(
+		(index: number) => {
+			const files = [...value]
+			files.splice(index, 1)
+
+			const event = { target: { files } }
+			onChange(event)
+		},
+		[value, onChange],
+	)
+
+	const multipleButtonText = value ? "Select new files" : "Select files"
+
+	const singleButtonText = value ? "Select new file" : "Select a file"
+	const buttonText = field.maxFiles > 1 ? multipleButtonText : singleButtonText
+
+	return (
+		<div className="flex flex-col gap-2">
+			<InputWithLabelAndHelpText helpText={updatedHelpText} severity={severity}>
+				<InputWithLabel
+					size={size}
+					severity={severity}
+					inputId={inputId}
+					labelId={labelId}
+					label={label}
+					image={showInputOnly ? undefined : field.image}
+				>
+					<div className="flex gap-2">
+						<Button
+							{...rest}
+							className="w-max"
+							variant="soft"
+							onClick={handleClick}
+							id="upload-input-upload-button"
+						>
+							<RiIcon icon="RiUpload2Line" /> {buttonText}
+						</Button>
+					</div>
+					<input
+						{...rest}
+						type="file"
+						ref={input}
+						id={inputId}
+						accept={field.extensions?.join(",")}
+						multiple={field.maxFiles > 1}
+						color={color}
+						style={{ display: "none" }}
+						{...fieldProps}
+						value=""
+					/>
+				</InputWithLabel>
+			</InputWithLabelAndHelpText>
+			{Array.isArray(value) && value.length > 0 && (
+				<div className="flex h-max flex-col gap-2">
+					{value.map((file, index) => (
+						<DisplayFile
+							key={index}
+							field={field}
+							file={file}
+							onRemove={() => {
+								handleRemove(index)
+							}}
+							disabled={rest.disabled}
+						/>
+					))}
+				</div>
+			)}
+		</div>
+	)
+})
+
+UploadInput.displayName = "UploadInput"
+
+interface DisplayFileProps {
+	file: File | Promise<File>
+	field: UploadField
+	disabled?: boolean
+	onRemove: () => void
+}
+
+const DisplayFile = memo((props: DisplayFileProps) => {
+	const { file, field, onRemove, disabled } = props
+	const [resolvedFile, setResolvedFile] = useState<File | null>(null)
+	const openFileViewer = useFileViewer()
+
+	const error = useMemo(() => resolvedFile && field.getError([resolvedFile]), [field, resolvedFile])
+
+	const { url, name } = useMemo(() => {
+		let url: string | null = null
+		let name: string
+		let size: string
+		// if the file is an image, create a URL for it
+		if (resolvedFile?.type.startsWith("image/")) {
+			url = URL.createObjectURL(resolvedFile)
+		}
+		if (resolvedFile) {
+			name = resolvedFile.name
+			size = convertBytesToLargestUnit(resolvedFile.size)
+		} else {
+			name = "Downloading..."
+			size = "..."
+		}
+		return { url, name, size }
+	}, [resolvedFile])
+
+	useEffect(() => {
+		if (file instanceof Promise) {
+			// failing to resolve file is not fatal (field would just say Downloading...)
+			file.then(setResolvedFile).catch(console.error)
+		} else {
+			setResolvedFile(file)
+		}
+	}, [file])
+
+	const handleDownload = useCallback(
+		(event: MouseEvent<HTMLButtonElement>) => {
+			event.stopPropagation()
+			if (!resolvedFile) {
+				throw new Error("Cannot download a file that is not resolved.")
+			}
+			const blob = new Blob([resolvedFile])
+			saveAs(blob, name)
+		},
+		[name, resolvedFile],
+	)
+
+	const handleDelete = useCallback(
+		(e: MouseEvent<HTMLButtonElement>) => {
+			e.stopPropagation()
+			onRemove()
+		},
+		[onRemove],
+	)
+
+	const handleCardClick = useCallback(() => {
+		if (!resolvedFile) return
+		openFileViewer((closeFileViewer) => ({
+			file: resolvedFile,
+			onDelete: !disabled
+				? () => {
+						onRemove()
+						closeFileViewer()
+					}
+				: undefined,
+		}))
+	}, [disabled, onRemove, openFileViewer, resolvedFile])
+
+	const rightSlotContent: ReactNode = useMemo(
+		() => (
+			<ButtonGroup variant="ghost" accentColor="base" size="sm">
+				<IconButton aria-label={`Download ${name}`} onClick={handleDownload} disabled={!resolvedFile}>
+					<RiIcon icon="RiDownload2Line" />
+				</IconButton>
+				{!disabled && (
+					<IconButton aria-label={`Remove ${name}`} disabled={disabled} onClick={handleDelete}>
+						<RiIcon icon="RiCloseLargeLine" />
+					</IconButton>
+				)}
+			</ButtonGroup>
+		),
+		[disabled, handleDelete, handleDownload, name, resolvedFile],
+	)
+
+	return url ? (
+		<ImageCard
+			style={{ cursor: "pointer" }}
+			onClick={handleCardClick}
+			file={resolvedFile}
+			error={error ?? undefined}
+			rightSlot={rightSlotContent}
+		/>
+	) : (
+		<FileCard
+			style={{ cursor: "pointer" }}
+			onClick={handleCardClick}
+			file={resolvedFile}
+			error={error ?? undefined}
+			rightSlot={rightSlotContent}
+		/>
+	)
+})
+
+DisplayFile.displayName = "DisplayFile"

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

@@ -0,0 +1,2 @@
+export * from "./UploadField"
+export * from "./UploadInput"

package/src/forms/fields/UploadField/utils.ts

@@ -0,0 +1,17 @@
+export const convertBytesToLargestUnit = (bytes: number) => {
+	// all files must be less than 50 MB
+	const units = ["byte", "kilobyte", "megabyte"]
+	let sizeInUnit = bytes
+	let unitIndex = 0
+	while (sizeInUnit > 1000 && unitIndex < units.length - 1) {
+		sizeInUnit /= 1000
+		unitIndex++
+	}
+	const formatter = new Intl.NumberFormat([], {
+		// 0 for bytes and kilobytes, 1 for megabytes
+		maximumFractionDigits: Math.max(0, unitIndex - 1),
+		style: "unit",
+		unit: units[unitIndex],
+	})
+	return formatter.format(sizeInUnit)
+}

package/src/forms/fields/constants.ts

@@ -0,0 +1,43 @@
+import { BooleanField, emptyBooleanField } from "./BooleanField"
+import { CustomField, emptyCustomField } from "./CustomField"
+import { DateField, emptyDateField } from "./DateField"
+import { emptyMultiStringField, MultiStringField } from "./MultiStringField"
+import { emptyNumberField, NumberField } from "./NumberField"
+import { emptyQrField, QrField } from "./QrField"
+import { emptyMultiSelectField, emptySelectField, MultiSelectField, SelectField } from "./SelectField"
+import { emptyStringField, emptyTextField, StringField, TextField } from "./StringOrTextFields"
+import { emptyUploadField, UploadField } from "./UploadField"
+
+export const FieldTypeToClsMapping = {
+	date: DateField,
+	number: NumberField,
+	boolean: BooleanField,
+	select: SelectField,
+	string: StringField,
+	text: TextField,
+	custom: CustomField,
+	upload: UploadField,
+	qr: QrField,
+	// TODO: Underscore
+	"multi-string": MultiStringField,
+	"multi-select": MultiSelectField,
+} as const
+
+export const FieldTypeToEmptyFieldMapping = {
+	date: emptyDateField,
+	number: emptyNumberField,
+	boolean: emptyBooleanField,
+	select: emptySelectField,
+	string: emptyStringField,
+	text: emptyTextField,
+	custom: emptyCustomField,
+	upload: emptyUploadField,
+	qr: emptyQrField,
+	// TODO: Underscore
+	"multi-string": emptyMultiStringField,
+	"multi-select": emptyMultiSelectField,
+} as const
+
+export const maxFileSizeMB = 50
+export const maxFileSizeKB = maxFileSizeMB * 1000
+export const maxFileSizeB = maxFileSizeKB * 1000

package/src/forms/fields/hooks.tsx

@@ -0,0 +1,26 @@
+import { ReactNode, useMemo } from "react"
+
+import { FieldValue } from "../typings"
+import { BaseField, BaseFormElement } from "./BaseField"
+import { GetInputProps } from "./typings"
+
+export const useFieldInput = <TField extends BaseFormElement | null>(
+	field: TField,
+	props: TField extends BaseFormElement ? GetInputProps<TField> : null,
+): ReactNode => {
+	// TODO: Consider deep equality check on props
+	return useMemo(() => {
+		if (!props || !field) return null
+		return field.getInput(props)
+	}, [field, props])
+}
+
+export const useFieldInputs = (fields: BaseFormElement[], props: GetInputProps<BaseField<FieldValue>>): ReactNode => {
+	const inputs = useMemo(() => {
+		return fields.map((field) => {
+			return <div key={field.getId()}>{field.getInput(props)}</div>
+		})
+	}, [fields, props])
+
+	return <div className="flex flex-col gap-2">{inputs}</div>
+}

package/src/forms/fields/index.ts

@@ -0,0 +1,12 @@
+export * from "./BaseField"
+export * from "./BooleanField"
+export * from "./DateField"
+export * from "./FieldSection"
+export * from "./hooks"
+export * from "./MultiStringField"
+export * from "./NumberField"
+export * from "./QrField"
+export * from "./SelectField"
+export * from "./StringOrTextFields"
+export * from "./typings"
+export * from "./utils"

package/src/forms/fields/typings.ts

@@ -0,0 +1,45 @@
+import { TextSize } from "@overmap-ai/blocks"
+import { HTMLProps, ReactNode } from "react"
+
+import { FormikUserFormRevision } from "../builder"
+import { Form } from "../typings"
+import { BaseField, BaseFormElement } from "./BaseField"
+
+export interface SchemaMeta {
+	readonly: boolean
+}
+
+export interface ISchema {
+	id?: string
+	fields: BaseFormElement[]
+	meta: SchemaMeta
+	title: ReactNode
+	description?: ReactNode
+}
+
+export type InputFieldLevelValidator<TValue> = (value: TValue | undefined) => string | null | undefined
+
+export type InputFormLevelValidator<TValue> = (
+	value: TValue | undefined,
+	allValues: Form | FormikUserFormRevision,
+) => string | null | undefined
+
+export type InputValidator<TValue> = InputFieldLevelValidator<TValue> | InputFormLevelValidator<TValue>
+
+export interface ComponentProps<TField extends BaseFormElement>
+	extends Omit<
+		HTMLProps<HTMLElement>,
+		"color" | "size" | "ref" | "type" | "onChange" | "onBlur" | "value" | "defaultValue" | "name" | "dir"
+	> {
+	field: TField
+	formId: string
+	size?: TextSize
+	showInputOnly?: boolean
+	internal?: boolean
+}
+
+export type GetInputProps<TField extends BaseFormElement> = Omit<ComponentProps<TField>, "field">
+
+// REASON: Sometimes, we literally accept any field.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyField = BaseField<any, any>

package/src/forms/fields/utils.ts

@@ -0,0 +1,125 @@
+import { ISerializedOnlyField, UserFormRevision } from "@overmap-ai/core"
+
+import { FieldTypeIdentifier, FieldValue, ISerializedField, SelectFieldOption, SerializedCondition } from "../typings"
+import { BaseField } from "./BaseField"
+import { FieldTypeToClsMapping } from "./constants"
+import { FieldSection } from "./FieldSection"
+import { AnyField, ISchema, SchemaMeta } from "./typings"
+
+// Note: the deserialization methods are separate to avoid circular dependencies.
+
+/** Deserializes anything but a FieldSection.
+ * @see `deserialize` for most use cases
+ */
+export const deserializeField = (serializedField: ISerializedOnlyField): AnyField => {
+	const fieldType: FieldTypeIdentifier = serializedField.type
+	const fieldCls = FieldTypeToClsMapping[fieldType]
+	return fieldCls.deserialize(serializedField)
+}
+
+/** Deserializes anything */
+export const deserialize = (serialized: ISerializedField): AnyField | FieldSection => {
+	if (serialized.type === "section") {
+		return FieldSection.deserialize(serialized)
+	}
+	return deserializeField(serialized)
+}
+
+export type PartialFormRevision = Pick<UserFormRevision, "title" | "fields" | "description"> & Partial<UserFormRevision>
+
+export function formRevisionToSchema(formRevision: PartialFormRevision, meta: Partial<SchemaMeta> = {}): ISchema {
+	// expanding the meta in order to set default values
+	const { readonly = false } = meta
+
+	return {
+		title: formRevision.title,
+		description: formRevision.description,
+		fields: formRevision.fields.map((serializedField: ISerializedField) => deserialize(serializedField)),
+		meta: { readonly },
+	}
+}
+
+export function flattenFields(schema: ISchema): AnyField[] {
+	const allFields: AnyField[] = []
+
+	for (const field of schema.fields) {
+		if (field instanceof FieldSection) {
+			for (const subField of field.fields) {
+				allFields.push(subField)
+			}
+		} else {
+			if (!(field instanceof BaseField)) {
+				throw new Error(`Invalid field type: ${field.type}`)
+			}
+			allFields.push(field)
+		}
+	}
+
+	return allFields
+}
+
+export function decodeFormValues(schema: ISchema, values: Record<string, string>): Record<string, FieldValue> {
+	const allFields: AnyField[] = flattenFields(schema)
+
+	const result: Record<string, FieldValue> = {}
+
+	for (const field of allFields) {
+		const value = values[field.identifier] ?? null
+
+		if (value !== null) {
+			result[field.identifier] = field.decodeJsonToValue(value) as FieldValue
+		} else {
+			result[field.identifier] = value
+		}
+	}
+
+	return result
+}
+
+export function encodeFormValues(schema: ISchema, values: Record<string, FieldValue>): Record<string, string> {
+	const allFields: AnyField[] = flattenFields(schema)
+
+	const result: Record<string, string> = {}
+
+	for (const field of allFields) {
+		const value = values[field.identifier]
+		result[field.identifier] = field.encodeValueToJson(value)
+	}
+
+	return result
+}
+
+export function valueIsFile(v: FieldValue | Promise<File>[] | undefined): v is File[] | Promise<File>[] {
+	return Array.isArray(v) && v.some((v: unknown) => v instanceof File || v instanceof Promise)
+}
+
+export function isConditionMet<TValue extends FieldValue | Promise<File>[]>(
+	condition: TValue extends FieldValue ? SerializedCondition<TValue> | null : null,
+	value: TValue,
+) {
+	// if no condition is provided, it is always met
+	if (!condition) return true
+
+	// conditions due not support file uploads, so we can assume that the value is not an array of File's
+	if (valueIsFile(value) || valueIsFile(condition.value)) throw new Error("Conditions do not support file uploads")
+
+	const valueAsPrimitive: Exclude<FieldValue, SelectFieldOption[] | File[]> = Array.isArray(value)
+		? value.map((v: string | SelectFieldOption) => (typeof v === "string" ? v : v.value))
+		: value
+
+	const valueToCompare: Exclude<FieldValue, SelectFieldOption[] | File[]> = Array.isArray(condition.value)
+		? condition.value.map((v: string | SelectFieldOption) => (typeof v === "string" ? v : v.value))
+		: condition.value
+
+	// if comparing arrays, check if any of the values match
+	if (Array.isArray(valueToCompare) && Array.isArray(valueAsPrimitive)) {
+		// ensure that every value in valueToCompare is in valueAsPrimitive
+		// though not necessarily the other way around
+		for (const v of valueToCompare) {
+			if (!valueAsPrimitive.includes(v)) return false
+		}
+		return true
+	}
+
+	return valueToCompare === value
+}

package/src/forms/index.ts

@@ -0,0 +1,5 @@
+export * from "./builder"
+export * from "./fields"
+export * from "./renderer"
+export * from "./typings"
+export { initialFormValues, validateForm } from "./utils"