useField

To make it easier to create new bound input components, the useField hook provides most of the functionality needed.

The first parameter is the name of the field you want to bind a component to, while the second (optional) parameter is a data object to bind. If no data object is specified, the hook will try to find a data object in the data object context.

The return value of the hook is an object with these properties:

• dataObject - A reference to the data object we are binding a component to

• error - If we failed to set the data object field value, this property will contain the error, otherwise it will be null

• setValue - The function that updates the data object field value. It takes a value, or a change event of the HTML input element

• value - The current value stored in the data object

• onKeyDown - A key down event handler that can be set on the input component. It will restore the saved value if the user clicks Escape while the input has focus

• onChange - A change event handler that can be passed to the component. If the component doesn't match the onChange signature, setValue should be used instead

• record - The current row of the data object

• reset - Restore the saved value for the bound field in the data object

Usage

As an example, this is the implementation of BoundTextField in the appframe-mui package:

import { forwardRef } from "react";

import { TextField, TextFieldProps } from "@mui/material";
import { useField } from "@olenbetong/appframe-react";

export type BoundTextFieldProps = TextFieldProps & {
  field: string;
};

export const BoundTextField = forwardRef<HTMLInputElement, BoundTextFieldProps>(
  function BoundTextField({ field, ...props }, ref) {
    let { error, value, onChange, onKeyDown } = useField<any, any>(field);

    if (props.type === "date" && value instanceof Date) {
      value = value.toISOString().split("T")[0];
    } else if (
      ["datetime", "datetime-local"].includes(props.type ?? "") &&
      value instanceof Date
    ) {
      value = value.toISOString();
    }

    return (
      <TextField
        error={!!error}
        fullWidth
        {...props}
        helperText={error ?? props.helperText}
        value={value ?? ""}
        onChange={onChange}
        onKeyDown={onKeyDown}
        inputRef={ref}
        InputLabelProps={{
          ...props.InputLabelProps,
          shrink: !!props.value ? true : props.InputLabelProps?.shrink,
        }}
      />
    );
  }
);

API

import { CurrentRow, DataObject } from "@olenbetong/appframe-data";

/**
 * Attempts to get a value of a field from a passed value. Can be a value, or
 * an event from a HTML input element.
 *
 * @param passedValue The passed value to get the value from
 */
export declare function getDataObjectFieldValue(passedValue: any): any;

/**
 * Attempts to set a value of a field in the data object. The value
 * can be an event from a HTML input, or the value itself.
 * The function will attempt to convert the value to the type of the field.
 *
 * @param dataObject Data object to set the fields value in
 * @param field Field to set the value of
 * @param passedValue The passed value to set the field to
 */
export declare function setDataObjectField<T = any, K extends keyof T = any>(
  dataObject: DataObject<T>,
  field: K,
  passedValue: any
): void;

export declare type useFieldRetunValue<T, V> = {
  dataObject: DataObject<T>;
  error: string | null;
  setValue: (value: V) => void;
  value: V | null;
  /**
   * Keydown event handler for the input field. Will cancel
   * the current field value when escape is pressed.
   */
  onKeyDown: (evt: React.KeyboardEvent<HTMLInputElement>) => void;
  onChange: (
    evt:
      | React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>
      | {
          target: {
            value: V | null;
          };
        },
    newValue?: V
  ) => void;
  record: CurrentRow<T>;
  /**
   * Reset the value to what is currently stored in the data object
   */
  reset: () => void;
};

/**
 * Returns the needed properties to bind a field to an input element.
 *
 * @param fieldName Field to bind to
 * @param dataObject Data object to bind to. Tries to get a data object from context if not given.
 * @returns value and onChange designed for HTML input fields
 */
export declare function useField<T = any, K extends keyof T = any>(
  fieldName: K,
  dataObject?: DataObject<T>
): useFieldRetunValue<T, T[K]>;