Field

[ecraig12345]

Preparation

• [x] Open GitHub issues related to component

  • 23943 (v0)

  • 23045 (v8)

• [x] Create react-* package and component from template
  • https://github.com/microsoft/fluentui/tree/master/packages/react-components/react-field
• [x] Component Spec authored and reviewed

Implementation

• [x] Component implementation
• [x] Initial conformance and unit tests (validate basic functionality)
• [x] Initial documentation
  • [x] Storybook stories
  • [x] README.md covering basic usage
  • [x] MIGRATION.md guide (include v8 and v0)
• [x] Component released as unstable from @fluentui/react-components/unstable

Validation

• [x] Add tests
  • [x] Unit and conformance tests
  • [x] VR tests
  • [x] Bundle size fixtures
  • [x] Performance test scenario
  • [x] Accessibility behavior tests
  • [x] #26604
• [x] Validate with partners
• [x] Finalize documentation
  • [x] Review and add any missing storybook stories
  • [x] Finalize migration guide
• [x] Component released as stable from @fluentui/react-components
  • [x] #27493
  • [x] Ensure exports are removed from from @fluentui/react-components/unstable
  • [x] In package.json: Remove the alpha/beta tag from the version number in package.json
  • [x] In package.json: Change beachball's disallowedChangeTypes to "major", "prerelease"

[ecraig12345]

Apparently I started working on an RFC for this a couple months ago but never got it to PR stage. Here's a preliminary version. It would be good to narrow down the options before making an actual RFC.

RFC: Field approach for @fluentui/react-components

Summary

We need a consistent way to handle label, description, and error message/state across all types of input components (Input, Slider, Checkbox, etc). The approach proposed here is to make a Field component with slots and children.

Background

Other libraries (including v8 and v0) have a variety of patterns for associating labels/etc with inputs. Some common examples (actual component names used vary):

// Each type of input component has props for label/etc
// (possibly with shared implementation)
<TextInput label="some field" description="much detail" required value="whatever" />

// Basic component wrapping the input + ___Field (or similar) variant with label/etc as props/slots
<TextInput value="whatever" />
<TextInputField label="some field" description="much detail" required value="whatever" />

// Wrapper field with components for each child
<FormField>
  <FormFieldLabel>some field</FormFieldLabel>
  <Input value="whatever" />
  <FormFieldHelperText>much detail</FormFieldHelperText>
</FormField>

// Wrapper field with props/slots for label/etc and input as child
<FormField label="some field" description="much detail" required>
  <TextInput value="whatever" />
</FormField>

More detailed list of examples: https://hackmd.io/OulpnA9eTEebdAc_0bVhMQ

Problem statement

We need a consistent way to handle label, description, and error message/state across all types of input components.

Desirable features:

• Auto-associate label and input (the less people have to do manually to get good a11y, the better)
• Easy to have consistent layout (spacing, relative positioning)
• Correctly apply error message attributes
• (eventually) Consistent validation handling across field types
• Minimal amount of typing to achieve a "normal form layout"
  • Must not require a parent form component

Open Questions

• Maybe: checkbox, radio, option are special and MUST have a label built in?
• how would someone change the layout? lots of positioning props? what if they wanted more customization?
  • For greater layout customization, use the hooks to make a new component? (have any partners validated the hook recomposition approach yet?)

Detailed Design or Proposal

There are multiple options under consideration, listed somewhat in order of the author's preference.

Option A: Field with input as child and slots for other parts

Have a field with the input as a child and slots for other parts. This control would be called Field to clarify that it's not limited to use within a <form>.

(Note: Input in the examples is specifically our text input component. You could substitute any input field component.)

<Field
  className="rootClass"
  label="hello"
  description={<div>fancy hello</div>}
  errorMessage="aka.ms/nohello"
  required
>
  <Input value="whatever" ... />
</Field>

Likely props/slots include:

• label slot with proper htmlFor association handled internally
• labelPosition string union with options for common layout needs
• description slot with proper aria-describedby association handled internally
• required either slot or boolean
• something for handling error messages and error state (TBD)

Option B: Field with slots for input/label/description

<Field
  className="rootClass"
  input={<Input value="whatever" />}
  label="hello"
  description={<div>fancy hello</div>}
  errorMessage="aka.ms/nohello"
  required
/>

This shares similar pros/cons of the first solution but is a bit more awkward API.

Option C: Field with children for input/label/description

Theoretically Field uses an internal context that our form label, error, description, and input/combobox/etc components use to set ids, error state, etc.

<Field id={requiredProp} required validationSomething={something?}>
  <FieldLabel>Email</FieldLabel>
  <Input />
  <FieldDescription>work email</FieldDescription>
  <FieldError>please enter a valid email</FieldError>
</Field>

<Field id={requiredProp2}>
  <FieldLabel>Country</FieldLabel>
  <FieldDescription>the world's only three countries</FieldDescription>
  <Select>
      <Option>USA</Option>
      <Option>UK</Option>
      <Option>India</Option>
  </Select>
</Field>

This might make it easier for people to customize the layout, but it creates challenges with knowing how to automatically apply a11y attributes or do automatic layout.

Probably-discarded solutions

Option D: Field hook

type FieldSlots = {
  input: IntrinsicShorthandProps<'input'>;
  label: IntrinsicShorthandProps<'label'>;
  description: IntrinsicShorthandProps<'span'>;
  errorText: IntrinsicShorthandProps<'span'>;
  required: unknown; // TBD
};

interface FieldProps extends ComponentProps<FieldSlots, 'input'> {
  labelPosition?: 'start' | 'end' | 'top' | 'bottom';
  // note: `size` is a native input prop name
  fieldSize?: 'small' | 'medium' | 'large';
  /** custom override for ID (generated ID used by default) */
  id?: string;
  // and some validation props maybe
}

interface FieldState {
  // stuff
}

const useField = <TProps extends FieldProps, TState extends FieldState>(props: TProps): TState => {
  // return field-related slots and state
};

const useFieldStyles = <TState extends FieldState>(state: TState) => {
  // styles for positioning/spacing of label, field, description, etc
};

// const renderField = <TState extends FieldState>(state: TState) => {
//   const { slots, slotProps } = getSlots<FieldSlots>(state, fieldShorthandProps);

// }

Option E: Input + InputField

Input stays as-is (basic component)

InputField

• what is the primary slot?

// some nuances TBD due to primary slot issues
type InputFieldSlots = FieldSlots & InputSlots;

interface InputProps extends InputProps, FieldProps {}

interface InputState extends InputState, FieldState {}

const useInputField = (props: InputProps, ref: React.Ref<HTMLInputElement>): InputState => {};

Option E1: InputField with DOM root as primary

<InputField
  className="rootClass"
  input={{
    // Input props
    className: 'inputClass',
  }}
/>

Option E2: InputField with input element as primary

<InputField
  className="inputClass"
  // how to give the root a class? same problem all over again :(
/>

Option F: Input includes Field features

downside: larger bundles

type InputSlots = FieldSlots & {
  /*more slots*/
};

interface InputProps extends FieldProps {
  /*more props*/
}

interface InputState extends FieldState {
  /*more state*/
}

const useInput = (props: InputProps, ref: React.Ref<HTMLInputElement>): InputState => {};

[ecraig12345]

Additional very preliminary notes about possible approaches for field groups...

Field Group + Label

The issue: group labels for groups of checkboxes and radios are often treated as if they were the same as field labels for text inputs, comboboxes, sliders, etc.

• The field label is "Name (4 to 8 characters):" here, and should use a <label> element:
• The group label is "Select a maintenance drone" here, and should use a <legend> element:

Group label option 1

We could make the FormField and FieldLabel components able to handle being a single field vs. a group of fields:

<FormField fieldType={FieldType.Group}>
  <FieldLabel>Favorite pet:</FieldLabel>
  <Radio label="Cat" />
  <Radio label="Dog" />
  <Radio label="Tribble" />
</FormField>

simplified output:

<fieldset>
  <legend>Favorite Pet:</legend>
  <label for="radio1">Cat</label>
  <input type="radio" id="radio1" name="group" />

  <label for="radio2">Dog</label>
  <input type="radio" id="radio2" name="group" />

  <label for="radio3">Tribble</label>
  <input type="radio" id="radio3" name="group" />
</fieldset>

Group label option 2

We could provide a more general FieldGroup component that could be used with checkboxes/radios, and could also be used to group other sets of components together (e.g. text fields in an address).

<FormGroup>
  <FormGroupLabel>Address</FormGroupLabel>
  <FormField>
    <FieldLabel>Street Address</FieldLabel>
    <InputField />
  </FormField>
  <FormField>
    <FieldLabel>City</FieldLabel>
    <InputField />
  </FormField>
  <FormField>
    <FieldLabel>Zip code</FieldLabel>
    <InputField />
  </FormField>
</FormGroup>

simplified output:

<fieldset>
  <legend>Address</legend>

  <div class="formfield">
    <label for="id1">Street Address</label>
    <input type="text" id="id1" />
  </div>

  <div class="formfield">
    <label for="id2">City</label>
    <input type="text" id="id2" />
  </div>

  <div class="formfield">
    <label for="id3">Zip code</label>
    <input type="text" id="id3" />
  </div>
</fieldset>

[behowell]

Field released as stable in #27493.