@fluentui/react-field 9.0.0-alpha.1

package/CHANGELOG.json

@@ -0,0 +1,119 @@
+{
+  "name": "@fluentui/react-field",
+  "entries": [
+    {
+      "date": "Thu, 15 Sep 2022 09:44:25 GMT",
+      "tag": "@fluentui/react-field_v9.0.0-alpha.1",
+      "version": "9.0.0-alpha.1",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "behowell@microsoft.com",
+            "package": "@fluentui/react-field",
+            "commit": "cd8f5a11fd89c77582950fe714fece2bdf9c08c0",
+            "comment": "Initial release"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-checkbox to v9.0.5",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-combobox to v9.0.0-beta.9",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-context-selector to v9.0.3",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-input to v9.1.0",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-label to v9.0.5",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-radio to v9.0.5",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-select to v9.0.0-beta.9",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-slider to v9.0.4",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-spinbutton to v9.0.1",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-switch to v9.0.5",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-textarea to v9.0.5",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-theme to v9.1.0",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-utilities to v9.1.0",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-conformance-griffel to v9.0.0-beta.13",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Wed, 03 Aug 2022 16:04:10 GMT",
+      "tag": "@fluentui/react-field_v9.0.0-alpha.0",
+      "version": "9.0.0-alpha.0",
+      "comments": {
+        "patch": [
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-field",
+            "comment": "Bump @fluentui/react-conformance-griffel to v9.0.0-beta.12",
+            "commit": "ee4a8be0d0831a6615f878f98db6a97cc61a802d"
+          }
+        ]
+      }
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Change Log - @fluentui/react-field
+
+This log was last generated on Thu, 15 Sep 2022 09:44:25 GMT and should not be manually modified.
+
+<!-- Start content -->
+
+## [9.0.0-alpha.1](https://github.com/microsoft/fluentui/tree/@fluentui/react-field_v9.0.0-alpha.1)
+
+Thu, 15 Sep 2022 09:44:25 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-field_v9.0.0-alpha.0..@fluentui/react-field_v9.0.0-alpha.1)
+
+### Changes
+
+- Initial release ([PR #24235](https://github.com/microsoft/fluentui/pull/24235) by behowell@microsoft.com)
+- Bump @fluentui/react-checkbox to v9.0.5 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-combobox to v9.0.0-beta.9 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-context-selector to v9.0.3 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-input to v9.1.0 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-label to v9.0.5 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-radio to v9.0.5 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-select to v9.0.0-beta.9 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-slider to v9.0.4 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-spinbutton to v9.0.1 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-switch to v9.0.5 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-textarea to v9.0.5 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-theme to v9.1.0 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-utilities to v9.1.0 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-conformance-griffel to v9.0.0-beta.13 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+
+## [9.0.0-alpha.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-field_v9.0.0-alpha.0)
+
+Wed, 03 Aug 2022 16:04:10 GMT
+
+### Patches
+
+- Bump @fluentui/react-conformance-griffel to v9.0.0-beta.12 ([PR #24131](https://github.com/microsoft/fluentui/pull/24131) by beachball)

package/LICENSE

@@ -0,0 +1,15 @@
+@fluentui/react-field
+
+Copyright (c) Microsoft Corporation
+
+All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ""Software""), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Note: Usage of the fonts and icons referenced in Fluent UI React is subject to the terms listed at https://aka.ms/fluentui-assets-license

package/README.md

@@ -0,0 +1,5 @@
+# @fluentui/react-field
+
+**React Field components for [Fluent UI React](https://react.fluentui.dev/)**
+
+These are not production-ready components and **should never be used in product**. This space is useful for testing new components whose APIs might change before final release.

package/Spec.md

@@ -0,0 +1,354 @@
+# @fluentui/react-field Spec
+
+## Background
+
+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
+
+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.
+
+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
+
+Each input component has a field version (such as `InputField`, `ComboboxField`, etc.) that includes the features of Field added to that component.
+
+```jsx
+<>
+  <InputField
+    // Field-specific props
+    label="This is the field label"
+    orientation="horizontal"
+    validationState="error"
+    validationMessage="This is error text"
+    // All props and slots of the underlying Input component are supported
+    required
+    size="small"
+    contentBefore="$"
+    contentAfter=".00"
+  />
+  <RadioGroupField label="Radio group field">
+    <Radio value="one" label="Option one" />
+    <Radio value="two" label="Option two" />
+    <Radio value="three" label="Option three" />
+  </RadioGroupField>
+  <ComboboxField label="Combobox field" validationState="success" validationMessage="Success text">
+    <Option value="one">Option one</Option>
+    <Option value="two">Option two</Option>
+    <Option value="three">Option three</Option>
+  </ComboboxField>
+  <SliderField label="Slider field" validationState="warning" validationMessage="Warning text" />
+  <SpinButtonField label="Spin button field" hint="Hint text" />
+</>
+```
+
+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<typeof Input>;
+
+export const InputField: ForwardRefComponent<InputFieldProps> = 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
+
+- **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
+
+### 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<T extends FieldComponent>`
+
+```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<HTMLElement>,
+    '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<T extends FieldComponent> = {
+  root: NonNullable<Slot<'div'>>;
+
+  /**
+   * 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<T>;
+
+  /**
+   * The label associated with the field.
+   */
+  label?: Slot<typeof Label>;
+
+  /**
+   * 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<T extends FieldComponent> = ComponentProps<Partial<FieldSlots<T>>, '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 <input> element has a `size` prop of type `number`.
+   */
+  size?: 'small' | 'medium' | 'large' | number;
+};
+```
+
+### State
+
+```ts
+export type FieldState<T extends FieldComponent> = ComponentState<Required<FieldSlots<T>>> &
+  Pick<FieldProps<T>, 'orientation' | 'validationState'> & {
+    classNames: SlotClassNames<FieldSlots<T>>;
+  };
+```
+
+### 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 API
+
+```jsx
+<InputField
+  label="This is the field label"
+  orientation="horizontal"
+  validationState="error"
+  validationMessage="This is a validation message"
+  hint="This is a hint message"
+/>
+```
+
+(similar API for other Field components)
+
+### Slot structure
+
+```jsx
+<slots.root>
+  <slots.label {...slotProps.label} />
+  <slots.control {...slotProps.control} />
+  <slots.validationMessage {...slotProps.validationMessage}>
+    <slots.validationMessageIcon {...slotProps.validationMessageIcon} />
+    {slotProps.validationMessage.children}
+  </slots.validationMessage>
+  <slots.hint {...slotProps.hint} />
+</slots.root>
+```
+
+### DOM structure
+
+```html
+<div className="fui-Field">
+  <label className="fui-Field__label fui-Label">This is the field label</label>
+  <!-- wrapped field component goes here -->
+  <span className="fui-Field__validationMessage">
+    <span className="fui-Field__validationMessageIcon"><svg>...</svg></span>
+    This is a validation message
+  </span>
+  <span className="fui-Field__hint">This is a hint message</span>
+</div>
+```
+
+## Migration
+
+### 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
+
+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
+
+### 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
+
+The Field itself is not interactive. The wrapped component has the same interactions as it does outside of a field.
+
+## Accessibility
+
+- **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.