@inventreedb/ui 0.0.1

package/src/components/forms/fields/ApiFormField.tsx

@@ -0,0 +1,281 @@
+import { t } from '@lingui/core/macro';
+import { Alert, FileInput, NumberInput, Stack, Switch } from '@mantine/core';
+import { useId } from '@mantine/hooks';
+import { useCallback, useEffect, useMemo } from 'react';
+import { type Control, type FieldValues, useController } from 'react-hook-form';
+
+import type { ApiFormFieldSet, ApiFormFieldType } from '@lib/types/Forms';
+import { isTrue } from '../../../functions/conversion';
+import { ChoiceField } from './ChoiceField';
+import DateField from './DateField';
+import { DependentField } from './DependentField';
+import IconField from './IconField';
+import { NestedObjectField } from './NestedObjectField';
+import { RelatedModelField } from './RelatedModelField';
+import { TableField } from './TableField';
+import TextField from './TextField';
+
+/**
+ * Render an individual form field
+ */
+export function ApiFormField({
+  fieldName,
+  definition,
+  control,
+  hideLabels,
+  url,
+  setFields,
+  onKeyDown
+}: Readonly<{
+  fieldName: string;
+  definition: ApiFormFieldType;
+  control: Control<FieldValues, any>;
+  hideLabels?: boolean;
+  url?: string;
+  setFields?: React.Dispatch<React.SetStateAction<ApiFormFieldSet>>;
+  onKeyDown?: (value: any) => void;
+}>) {
+  const fieldId = useId();
+  const controller = useController({
+    name: fieldName,
+    control
+  });
+  const {
+    field,
+    fieldState: { error }
+  } = controller;
+  const { value, ref } = field;
+
+  useEffect(() => {
+    if (
+      definition.field_type === 'nested object' ||
+      definition.field_type === 'dependent field'
+    )
+      return;
+
+    // hook up the value state to the input field
+    if (definition.value !== undefined) {
+      field.onChange(definition.value);
+    }
+  }, [definition.value]);
+
+  const fieldDefinition: ApiFormFieldType = useMemo(() => {
+    return {
+      ...definition,
+      label: hideLabels ? undefined : definition.label,
+      description: hideLabels ? undefined : definition.description
+    };
+  }, [hideLabels, definition]);
+
+  // pull out onValueChange as this can cause strange errors when passing the
+  // definition to the input components via spread syntax
+  const reducedDefinition = useMemo(() => {
+    return {
+      ...fieldDefinition,
+      onValueChange: undefined,
+      adjustFilters: undefined,
+      adjustValue: undefined,
+      read_only: undefined,
+      children: undefined,
+      exclude: undefined
+    };
+  }, [fieldDefinition]);
+
+  // Callback helper when form value changes
+  const onChange = useCallback(
+    (value: any) => {
+      let rtnValue = value;
+      // Allow for custom value adjustments (per field)
+      if (definition.adjustValue) {
+        rtnValue = definition.adjustValue(value);
+      }
+
+      field.onChange(rtnValue);
+
+      // Run custom callback for this field
+      definition.onValueChange?.(rtnValue);
+    },
+    [fieldName, definition]
+  );
+
+  // Coerce the value to a numerical value
+  const numericalValue: number | '' = useMemo(() => {
+    let val: number | '' = 0;
+
+    switch (definition.field_type) {
+      case 'integer':
+        val = Number.parseInt(value) ?? '';
+        break;
+      case 'decimal':
+      case 'float':
+      case 'number':
+        val = Number.parseFloat(value) ?? '';
+        break;
+      default:
+        break;
+    }
+
+    if (Number.isNaN(val) || !Number.isFinite(val)) {
+      val = '';
+    }
+
+    return val;
+  }, [definition.field_type, value]);
+
+  // Coerce the value to a (stringified) boolean value
+  const booleanValue: boolean = useMemo(() => {
+    return isTrue(value);
+  }, [value]);
+
+  // Construct the individual field
+  const fieldInstance = useMemo(() => {
+    switch (fieldDefinition.field_type) {
+      case 'related field':
+        return (
+          <RelatedModelField
+            controller={controller}
+            definition={fieldDefinition}
+            fieldName={fieldName}
+          />
+        );
+      case 'email':
+      case 'url':
+      case 'string':
+        return (
+          <TextField
+            definition={reducedDefinition}
+            controller={controller}
+            fieldName={fieldName}
+            onChange={onChange}
+            onKeyDown={(value) => {
+              onKeyDown?.(value);
+            }}
+          />
+        );
+      case 'icon':
+        return (
+          <IconField definition={fieldDefinition} controller={controller} />
+        );
+      case 'boolean':
+        return (
+          <Switch
+            {...reducedDefinition}
+            checked={booleanValue}
+            ref={ref}
+            id={fieldId}
+            aria-label={`boolean-field-${fieldName}`}
+            radius='lg'
+            size='sm'
+            error={definition.error ?? error?.message}
+            onChange={(event) => onChange(event.currentTarget.checked)}
+          />
+        );
+      case 'date':
+      case 'datetime':
+        return (
+          <DateField controller={controller} definition={fieldDefinition} />
+        );
+      case 'integer':
+      case 'decimal':
+      case 'float':
+      case 'number':
+        return (
+          <NumberInput
+            {...reducedDefinition}
+            radius='sm'
+            ref={field.ref}
+            id={fieldId}
+            aria-label={`number-field-${field.name}`}
+            value={numericalValue}
+            error={definition.error ?? error?.message}
+            decimalScale={definition.field_type == 'integer' ? 0 : 10}
+            onChange={(value: number | string | null) => onChange(value)}
+            step={1}
+          />
+        );
+      case 'choice':
+        return (
+          <ChoiceField
+            controller={controller}
+            fieldName={fieldName}
+            definition={fieldDefinition}
+          />
+        );
+      case 'file upload':
+        return (
+          <FileInput
+            {...reducedDefinition}
+            id={fieldId}
+            ref={field.ref}
+            radius='sm'
+            value={value}
+            error={definition.error ?? error?.message}
+            onChange={(payload: File | null) => onChange(payload)}
+          />
+        );
+      case 'nested object':
+        return (
+          <NestedObjectField
+            definition={fieldDefinition}
+            fieldName={fieldName}
+            control={control}
+            url={url}
+            setFields={setFields}
+          />
+        );
+      case 'dependent field':
+        return (
+          <DependentField
+            definition={fieldDefinition}
+            fieldName={fieldName}
+            control={control}
+            url={url}
+            setFields={setFields}
+          />
+        );
+      case 'table':
+        return (
+          <TableField
+            definition={fieldDefinition}
+            fieldName={fieldName}
+            control={controller}
+          />
+        );
+      default:
+        return (
+          <Alert color='red' title={t`Error`}>
+            Invalid field type for field '{fieldName}': '
+            {fieldDefinition.field_type}'
+          </Alert>
+        );
+    }
+  }, [
+    booleanValue,
+    control,
+    controller,
+    definition,
+    field,
+    fieldId,
+    fieldName,
+    fieldDefinition,
+    numericalValue,
+    onChange,
+    onKeyDown,
+    reducedDefinition,
+    ref,
+    setFields,
+    value
+  ]);
+
+  if (fieldDefinition.hidden) {
+    return null;
+  }
+
+  return (
+    <Stack>
+      {definition.preFieldContent}
+      {fieldInstance}
+      {definition.postFieldContent}
+    </Stack>
+  );
+}

package/src/components/forms/fields/ChoiceField.tsx

@@ -0,0 +1,86 @@
+import type { ApiFormFieldType } from '@lib/types/Forms';
+import { Select } from '@mantine/core';
+import { useId } from '@mantine/hooks';
+import { useCallback, useMemo } from 'react';
+import type { FieldValues, UseControllerReturn } from 'react-hook-form';
+
+/**
+ * Render a 'select' field for selecting from a list of choices
+ */
+export function ChoiceField({
+  controller,
+  definition,
+  fieldName
+}: Readonly<{
+  controller: UseControllerReturn<FieldValues, any>;
+  definition: ApiFormFieldType;
+  fieldName: string;
+}>) {
+  const fieldId = useId();
+
+  const {
+    field,
+    fieldState: { error }
+  } = controller;
+
+  const { value } = field;
+
+  // Build a set of choices for the field
+  const choices: any[] = useMemo(() => {
+    const choices = definition.choices ?? [];
+
+    // TODO: Allow provision of custom render function also
+
+    return choices.map((choice) => {
+      return {
+        value: choice.value.toString(),
+        label: choice.display_name ?? choice.value
+      };
+    });
+  }, [definition.choices]);
+
+  // Update form values when the selected value changes
+  const onChange = useCallback(
+    (value: any) => {
+      // Prevent blank values if the field is required
+      if (definition.required && !value) {
+        return;
+      }
+
+      field.onChange(value);
+
+      // Run custom callback for this field (if provided)
+      definition.onValueChange?.(value);
+    },
+    [field.onChange, definition]
+  );
+
+  const choiceValue = useMemo(() => {
+    if (!value) {
+      return '';
+    } else {
+      return value.toString();
+    }
+  }, [value]);
+
+  return (
+    <Select
+      id={fieldId}
+      aria-label={`choice-field-${field.name}`}
+      error={definition.error ?? error?.message}
+      radius='sm'
+      {...field}
+      onChange={onChange}
+      data={choices}
+      value={choiceValue}
+      label={definition.label}
+      description={definition.description}
+      placeholder={definition.placeholder}
+      required={definition.required}
+      disabled={definition.disabled}
+      leftSection={definition.icon}
+      comboboxProps={{ withinPortal: true }}
+      searchable
+    />
+  );
+}

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

@@ -0,0 +1,79 @@
+import type { ApiFormFieldType } from '@lib/types/Forms';
+import { DateInput } from '@mantine/dates';
+import dayjs from 'dayjs';
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+import { useCallback, useId, useMemo } from 'react';
+import type { FieldValues, UseControllerReturn } from 'react-hook-form';
+
+dayjs.extend(customParseFormat);
+
+export default function DateField({
+  controller,
+  definition
+}: Readonly<{
+  controller: UseControllerReturn<FieldValues, any>;
+  definition: ApiFormFieldType;
+}>) {
+  const fieldId = useId();
+
+  const {
+    field,
+    fieldState: { error }
+  } = controller;
+
+  const valueFormat = useMemo(() => {
+    // Determine the format based on the field type
+    return definition.field_type == 'date'
+      ? 'YYYY-MM-DD'
+      : 'YYYY-MM-DD HH:mm:ss';
+  }, [definition.field_type]);
+
+  const onChange = useCallback(
+    (value: any) => {
+      // Convert the returned date object to a string
+      if (value) {
+        value = value.toString();
+        value = dayjs(value).format(valueFormat);
+        value = value.toString().split('T')[0];
+      }
+
+      field.onChange(value);
+      definition.onValueChange?.(value);
+    },
+    [field.onChange, definition, valueFormat]
+  );
+
+  const dateValue: Date | null = useMemo(() => {
+    let dv: Date | null = null;
+
+    if (field.value) {
+      dv = dayjs(field.value).toDate();
+    }
+
+    // Ensure that the date is valid
+    if (dv instanceof Date && !Number.isNaN(dv.getTime())) {
+      return dv;
+    } else {
+      return null;
+    }
+  }, [field.value]);
+
+  return (
+    <DateInput
+      id={fieldId}
+      aria-label={`date-field-${field.name}`}
+      radius='sm'
+      ref={field.ref}
+      type={undefined}
+      error={definition.error ?? error?.message}
+      value={dateValue}
+      clearable={!definition.required}
+      onChange={onChange}
+      valueFormat={valueFormat}
+      label={definition.label}
+      description={definition.description}
+      placeholder={definition.placeholder}
+      leftSection={definition.icon}
+    />
+  );
+}

package/src/components/forms/fields/DependentField.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useMemo } from 'react';
+import {
+  type Control,
+  type FieldValues,
+  useFormContext
+} from 'react-hook-form';
+
+import type { ApiFormFieldSet, ApiFormFieldType } from '@lib/types/Forms';
+import { useApi } from '../../../contexts/ApiContext';
+import {
+  constructField,
+  extractAvailableFields
+} from '../../../functions/forms';
+import { ApiFormField } from './ApiFormField';
+
+export function DependentField({
+  control,
+  fieldName,
+  definition,
+  url,
+  setFields
+}: Readonly<{
+  control: Control<FieldValues, any>;
+  definition: ApiFormFieldType;
+  fieldName: string;
+  url?: string;
+  setFields?: React.Dispatch<React.SetStateAction<ApiFormFieldSet>>;
+}>) {
+  const api = useApi();
+  const { watch, resetField } = useFormContext();
+
+  const mappedFieldNames = useMemo(
+    () =>
+      (definition.depends_on ?? []).map((f) =>
+        [...fieldName.split('.').slice(0, -1), f].join('.')
+      ),
+    [definition.depends_on]
+  );
+
+  useEffect(() => {
+    const { unsubscribe } = watch(async (values, { name }) => {
+      // subscribe only to the fields that this field depends on
+      if (!name || !mappedFieldNames.includes(name)) return;
+      if (!url || !setFields) return;
+
+      const res = await api.options(url, {
+        data: values // provide the current form state to the API
+      });
+
+      const fields: Record<string, ApiFormFieldType> | null =
+        extractAvailableFields(res, 'POST');
+
+      // update the fields in the form state with the new fields
+      setFields((prevFields) => {
+        const newFields: Record<string, ReturnType<typeof constructField>> = {};
+
+        for (const [k, v] of Object.entries(prevFields)) {
+          newFields[k] = constructField({
+            field: v,
+            definition: fields?.[k]
+          });
+        }
+
+        return newFields;
+      });
+
+      // reset the current field and all nested values with undefined
+      resetField(fieldName, {
+        defaultValue: undefined,
+        keepDirty: true,
+        keepTouched: true
+      });
+    });
+
+    return () => unsubscribe();
+  }, [mappedFieldNames, url, setFields, resetField, fieldName]);
+
+  if (!definition.child) {
+    return null;
+  }
+
+  return (
+    <ApiFormField
+      control={control}
+      fieldName={fieldName}
+      definition={definition.child}
+      url={url}
+      setFields={setFields}
+    />
+  );
+}