V0 FormField Migration to V9

[chpalac]

V0 FormField has some usages, from simple to complex, which we are trying to create a shim to support the migration to V9 using Field. We need some orientation on how to best do it for some cases, since the V9 Field is tighted to the possible inputs available in V9, making it difficute to use it together with custom inputs.

I have made this Codesandbox with few V0 FormField usages, where we have the custom control component is where our questions are. There's no straightfoward way to use useField and build it to be that generic in the current implementation. we have started the idea of a shim that looks like the following:

import * as React from 'react';
import { useField_unstable, useFieldStyles_unstable, renderField_unstable } from '@fluentui/react-field';
import { FieldPropsWithOptionalComponentProps } from '../../components/Field/Field.types';
interface CustomInputFieldProps {
  errorMessage?:
    | {
        content: string;
      }
    | string;
  required?: boolean;
  control: {
    content: React.ReactNode;
  };
  label: React.ReactElement | { content: React.ReactElement };
}
const DummyVoidFunctionComponent: React.VoidFunctionComponent<
  Pick<
    React.HTMLAttributes<HTMLElement>,
    'id' | 'className' | 'style' | 'aria-labelledby' | 'aria-describedby' | 'aria-invalid' | 'aria-errormessage'
  >
> = () => {
  return null;
};
const CustomInputField = React.forwardRef<HTMLInputElement, CustomInputFieldProps>((props, ref) => {
  const { errorMessage, required, control, label } = props;
  const fieldProps: FieldPropsWithOptionalComponentProps<typeof DummyVoidFunctionComponent> = { required: required };
  if (errorMessage) {
    fieldProps.validationState = 'error';
    if (typeof errorMessage === 'object') {
      fieldProps.validationMessage = errorMessage.content;
    }
    if (typeof errorMessage === 'string') {
      fieldProps.validationMessage = errorMessage;
    }
  }
  if (label) {
    if (label.content) {
      fieldProps.label = label.content;
    } else {
      fieldProps.label = label;
    }
  }
  fieldProps.control = { children: () => control.content };
  const state = useField_unstable(fieldProps, ref, {
    component: DummyVoidFunctionComponent,
    classNames: {
      root: 'foo',
      control: 'foo',
      hint: 'foo',
      label: 'foo',
      validationMessage: 'foo',
      validationMessageIcon: 'foo',
    },
  });
  useFieldStyles_unstable(state);
  return renderField_unstable(state);
});

// Usage
export const CustomInput = () => (
  <CustomInputField
    required
    errorMessage={{ content: 'This is an error message' }}
    control={{ content: <input type="text" /> }}
    label="This is a label"
  />
);

We are trying to figure out if that is the best way to keep the refactor and how do we want to support those cases.

[smhigley]

We went back and forth a few times on whether to have a generic <Field> component, or individual <XField> components, and landed on the latter for a few reasons, including variations in how components are named (e.g. Checkbox/RadioGroup being different, and some components natively supporting htmlFor/id, and some needing ARIA).

I believe the goal was still to have a Field pattern that makes it very easy to generate new XField components, but I'll tag @behowell, since he worked on the Field component.

[behowell]

Yeah, like @smhigley mentioned, Field is designed like a higher-order component that wraps an input component. Each individual form control uses the Field hooks to create an e.g. InputField or RadioGroupField, etc.

There are a few things that could make it easier to use with custom controls, which aren't specifically planned, but we could consider them:

1. A makeField function that wraps a given component, rather than needing to use the useField_unstable, etc. hooks. This would make it simpler to create a field from any given input component.

   const MyInputField = makeField(MyInput);
   
   <MyInputField label="ExampleLabel" />

2. A generic CustomField (name could be better), which takes the input element as its child, and sets props like aria-labelledby directly on the child, like:

   <CustomField label="Example label">
     <MyInput /> {/* gets aria-labelledby="..." set on it by the CustomField */}
   </CustomField>

It sounds like 2 is similar to what you've prototyped in this post. If it's required for v0 migration, we might want to more seriously consider including it as part of the @fluentui/react-field package, so you don't have to implement it solely for v0 compatibility.

[behowell]

After discussing with the team, we've decided to go with a third option:

3. Export the individual pieces of a field as separate components, like <FieldLayout>, <FieldLabel> and <FieldMessage>. The user would be responsible for hooking up props between them (like htmlFor and aria-labelledby), but it would allow a Fluent v9 field to be constructed from its parts. Something like this: (very much TBD exactly how it would work)

   <FieldLayout>
     <FieldLabel htmlFor="my-input">Example label</FieldLabel>
     <MyInput id="my-input" aria-invalid="true" aria-errormessage="my-error-message" aria-describedby="my-hint" />
     <FieldMessage id="my-error-message" validationState="error">Example error message</FieldMessage>
     <FieldMessage id="my-hint">Example hint text</FieldMessage>
   </FieldLayout>

I've logged #25500 to investigate further and implement this solution.