diff --git a/packages/react-components/react-field/Spec.md b/packages/react-components/react-field/Spec.md index b232ee1f411d7a..eab2c880350bf3 100644 --- a/packages/react-components/react-field/Spec.md +++ b/packages/react-components/react-field/Spec.md @@ -2,62 +2,353 @@ ## Background -_Description and use cases of this component_ +Field adds a label, validation text, and hint text to form input components. The existing input components (such as `Input` and `Combobox`) are wrapped to create field versions of them (such as `InputField` and `ComboboxField`). + +Epic issue tracking implementation: https://github.com/microsoft/fluentui/issues/19627 ## Prior Art -_Include background research done for this component_ +Existing libraries tend to take one of the following approaches to field. + +1. Include support for label, error text, etc. in the base input component. Libraries using this approach include: + - **FluentUI v8** - [`TextField`](https://developer.microsoft.com/en-us/fluentui#/controls/web/textfield), [`Dropdown`](https://developer.microsoft.com/en-us/fluentui#/controls/web/dropdown), [`ChoiceGroup`](https://developer.microsoft.com/en-us/fluentui#/controls/web/choicegroup), etc. + - **Spectrum** - [`TextField`](https://react-spectrum.adobe.com/react-spectrum/TextField.html), [`Slider`](https://react-spectrum.adobe.com/react-spectrum/Slider.html), [`RadioGroup`](https://react-spectrum.adobe.com/react-spectrum/RadioGroup.html), etc. +2. Provide a set of components that are manually constructed into a field. This requires manually hooking up the components using props like `htmlFor` and `aria-describedby`. Libraries using this approach include: + - **FluentUI v0** - [`FormField`](https://fluentsite.z22.web.core.windows.net/0.64.0/components/form/props#form-field), [`FormLabel`](https://fluentsite.z22.web.core.windows.net/0.64.0/components/form/props#form-label), [`FormMessage`](https://fluentsite.z22.web.core.windows.net/0.64.0/components/form/props#form-message) + - **Ant** - [`Form.Item`](https://ant.design/components/form/#Form.Item) (uses context to do some of the hooking up between the item and the field component). +3. Provide base components without a label or descriptive text, and then Field versions of those controls. Libraries using this approach include: + - **FluentUI v0** - [`Input`](https://fluentsite.z22.web.core.windows.net/0.64.0/components/input/props) and [`FormInput`](https://fluentsite.z22.web.core.windows.net/0.64.0/components/form/props#form-input), for example. + - **Evergreen UI** - [`TextInput`](https://evergreen.segment.com/components/text-input) and [`TextInputField`](https://evergreen.segment.com/components/text-input#textinputfield), for example. -- _Link to Open UI research_ -- _Link to comparison of v7 and v0_ -- _Link to GitHub epic issue for the converged component_ +The Field implementation in this spec follows pattern (3). There are Field versions of all components that can be used as form inputs. There are several reasons, including: + +- **Accessibility**: By combining a base component with the field props into a single component, all of the accessibility props like `htmlFor` and `aria-describedby` are set correctly for "free". +- **Simplicity**: All props related to the component (such as `label`, `id`, `validationState="error"`, etc.) are on the same component, rather than split between multiple components (like separate `Field` and `Input` components). +- **Consistency**: All of the Field components share a common set of props for the label, validationState, hint, etc. +- **Bundle size**: When the label and other field functionality is not needed, it is still possible to use the base components without pulling in unnecessary dependencies (like `Label` and the field styling). ## Sample Code -_Provide some representative example code that uses the proposed API for the component_ +Each input component has a field version (such as `InputField`, `ComboboxField`, etc.) that includes the features of Field added to that component. + +```jsx +<> + + + + + + + + + + + + + + +``` + +These field versions of the components use a common set of Field hooks, and can be defined using very little code. + +```ts +export type InputFieldProps = FieldProps; + +export const InputField: ForwardRefComponent = React.forwardRef((props, ref) => { + const state = useField_unstable(props, ref, Input); + useFieldStyles_unstable(state); + return renderField_unstable(state); +}); + +InputField.displayName = 'InputField'; +``` + +## Components + +The following field components will be defined. If more form components are added in the future, they should also include a Field version. + +- `CheckboxField` +- `ComboboxField` +- `DropdownField` +- `InputField` +- `RadioGroupField` +- `SelectField` +- `SliderField` +- `SpinButtonField` +- `SwitchField` +- `TextareaField` ## Variants -_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._ +- **Orientation**: The `orientation` prop affects the layout of the label and field component: + - `'vertical'` (default) - label is above the field component + - `'horizontal'` - label is to the left of the field component, and is 33% the width of the field (this allows multiple stacked fields to all align their labels) +- **Validation state**: The `validationState` prop affects the icon and color used by the `validationMessage`: + - `'error'` - Red x icon, red text color + - `'warning'` - Yellow exclamation icon, neutral color text + - `'success'` - Green check icon, neutral color text + - `undefined` (default): No validation message icon, neutral color text +- **Error**: Some control types (like `Input` and `Combobox`) have a prop that makes the border red. This prop will be set `validationState="error"`. + +Field also forwards some props from the wrapped component to the label as well: + +- **Size**: If the wrapped component supports a `size` prop, it will also be applied to the field's label. +- **Required**: If set, the Label will get a required asterisk: `*` ## API -_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_ +### FieldComponent + +The `FieldComponent` type defines the minimum set of props that the wrapped component must support. This is used for the generic types as the requirement for the type parameter: `FieldProps` + +```ts +/** + * The minimum requirement for a component used by Field. + * + * Note: the use of VoidFunctionComponent means that component is not *required* to have a children prop, + * but it is still allowed to have a children prop. + */ +export type FieldComponent = React.VoidFunctionComponent< + Pick< + React.HTMLAttributes, + 'id' | 'className' | 'style' | 'aria-labelledby' | 'aria-describedby' | 'aria-invalid' | 'aria-errormessage' + > +>; +``` + +### Slots + +_Note: TypeScript crashes if the `Slot` type is used with a template type parameter. The `SlotComponent` type is a simplified version of that type, which only supports `React.ComponentType`/`React.VoidFunctionComponent`._ + +```ts +export type FieldSlots = { + root: NonNullable>; + + /** + * The underlying component wrapped by this field. + * + * This is the PRIMARY slot: all intrinsic HTML properties will be applied to this slot, + * except `className` and `style`, which remain on the root slot. + */ + control: SlotComponent; + + /** + * The label associated with the field. + */ + label?: Slot; + + /** + * A message about the validation state. The appearance of the `validationMessage` depends on `validationState`. + */ + validationMessage?: Slot<'span'>; + + /** + * The icon associated with the `validationMessage`. If the `validationState` prop is set, this will default to an + * icon corresponding to that state. + * + * This will only be displayed if `validationMessage` is set. + */ + validationMessageIcon?: Slot<'span'>; + + /** + * Additional hint text below the field. + */ + hint?: Slot<'span'>; +}; +``` + +### Props + +```ts +export type FieldProps = ComponentProps>, 'control'> & { + /** + * The orientation of the label relative to the field component. + * This only affects the label, and not the validationMessage or hint (which always appear below the field component). + * + * @default vertical + */ + orientation?: 'vertical' | 'horizontal'; + + /** + * The `validationState` affects the color of the `validationMessage`, the `validationMessageIcon`, and for some + * field components, an `validationState="error"` causes the border to become red. + * + * @default undefined + */ + validationState?: 'error' | 'warning' | 'success'; +}; +``` + +Field also reads some props from the underlying component. These are not part of `FieldProps` because they are not added to the components that don't support them. However, they are accepted by `useField`: + +```ts +/** + * Props that are supported by Field, but not required to be supported by the component that implements field. + */ +export type OptionalFieldComponentProps = { + /** + * Whether the field label should be marked as required. + */ + required?: boolean; + + /** + * Size of the field label. + * + * Number sizes will be ignored, but are allowed because the HTML element has a `size` prop of type `number`. + */ + size?: 'small' | 'medium' | 'large' | number; +}; +``` + +### State + +```ts +export type FieldState = ComponentState>> & + Pick, 'orientation' | 'validationState'> & { + classNames: SlotClassNames>; + }; +``` + +### Label for Checkbox and Switch + +The Checkbox and Switch components already have a `label` prop, which conflicts with the Field's `label`. + +#### `CheckboxField` + +- The `label` prop will go to the Checkbox and NOT the Field +- New `fieldLabel` prop for the label of the Field + +#### `SwitchField` + +- New `valueLabel` prop for the label of the Switch +- The `label` prop will go to the Field and NOT the Switch ## Structure -- _**Public**_ -- _**Internal**_ -- _**DOM** - how the component will be rendered as HTML elements_ +### Public API + +```jsx + +``` + +(similar API for other Field components) + +### Slot structure + +```jsx + + + + + + {slotProps.validationMessage.children} + + + +``` + +### DOM structure + +```html +
+ + + + ... + This is a validation message + + This is a hint message +
+``` ## Migration -_Describe what will need to be done to upgrade from the existing implementations:_ +### Migration from v8 + +Migration from v8 will require picking between the normal and `Field` version of an input control, depending on whether the field-specific features are required: (`label`, `validationState="error"`, `validationMessage`, `hint`) + +See individual input components for more detailed migration guides. + +| v8 Control | v9 Base control | v9 Field control | Notes | +| ------------- | --------------------- | ------------------------------- | -------------------------------------------------------------------------------------------- | +| `Checkbox` | `Checkbox` | `CheckboxField` | Only use `CheckboxField` if an error message is needed, or if required for layout in a form. | +| `ChoiceGroup` | `RadioGroup` | `RadioGroupField` | | +| `ComboBox` | `Combobox` | `ComboboxField` | `errorMessage="..."` is replaced by `validationState="error" validationMessage="..."` | +| `Dropdown` | `Dropdown` | `DropdownField` | `errorMessage="..."` is replaced by `validationState="error" validationMessage="..."` | +| `Slider` | `Slider` | `SliderField` | | +| `SpinButton` | `SpinButton` | `SpinButtonField` | | +| `TextField` | `Input` OR `Textarea` | `InputField` OR `TextareaField` | `errorMessage="..."` is replaced by `validationState="error" validationMessage="..."` | +| `Toggle` | `Switch` | `SwitchField` | | + +### Migration from v0 -- _Migration from v8_ -- _Migration from v0_ +Many components in v0 have `Form___` versions (such as `FormInput`). Those are replaced by the `___Field` equivalent. See the underlying component's migration guides for more detailed migration information. + +Component mapping: + +- `FormButton` => Not supported +- `FormCheckbox` => `CheckboxField` OR `SwitchField` +- `FormDatepicker` => _(Not yet implemented)_ +- `FormDropdown` => `DropdownField` +- `FormField` => Not supported +- `FormFieldCustom` => Not supported +- `FormLabel` => The `label` prop of the field component +- `FormMessage` => Either the `validationMessage` or `hint` prop of the field component +- `FormRadioGroup` => `RadioGroupField` +- `FormSlider` => `SliderField` +- `FormTextArea` => `TextareaField` + +The following props are common to each of the `Form___` components: + +- `label` => `label` +- `message` => either `validationMessage` or `hint` +- `errorMessage` => `validationMessage` with `validationState="error"` ## Behaviors -_Explain how the component will behave in use, including:_ +### Form validation + +Field has no logic to perform input validation. It is expected that the validation will be done externally (possibly using a third party form validation library like Formik). + +### Interaction -- _Component States_ -- _Interaction_ - - _Keyboard_ - - _Cursor_ - - _Touch_ - - _Screen readers_ +The Field itself is not interactive. The wrapped component has the same interactions as it does outside of a field. ## Accessibility -Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document. - -- Decide whether to use **native element** or folow **ARIA** and provide reasons -- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible. -- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props. -- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used -- Specify texts for **state change announcements** - [ARIA live regions - ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...) -- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them -- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation) -- List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases) +- **ARIA pattern** + - Field itself does not implement a defined ARIA pattern. It has no role applied to the root element. +- **Attributes** + - The following are applied on the wrapped component: + - `aria-labelledby={label.id}`, if the label is present. + - `aria-describedby` is set to one of: + - `aria-describedby={validationMessage.id}`, if validationMessage is present, and _only if_ `validationState !== 'error'` + - `aria-describedby={hint.id}`, if hint is present + - `aria-describedby={validationMessage.id + ' ' + hint.id}`, if both conditions above apply + - `aria-errormessage={validationMessage.id}`, if validationMessage is present, and _only if_ `validationState === 'error'` + - `aria-invalid={true}`, _only if_ `validationState === 'error'` + - On the `label` slot: + - `htmlFor={control.id}` - the wrapped component's `id` (an ID is generated if not supplied via props). +- **Live regions** (state change announcements) + - TBD: Need to determine if the validation message should be an aria live region. +- **UI parts appearing on hover or focus** + - None. +- **Focus behavior** + - No special focus behavior: no focus trapping or programmatic focus moving.