feat(react-field): add useFieldBase_unstable hook

change/@fluentui-react-field-1731d3b5-2249-4453-8366-3556b93f5000.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add base hooks for Field",
+  "packageName": "@fluentui/react-field",
+  "email": "dmytrokirpa@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-field/library/src/components/Field/Field.types.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { Label } from '@fluentui/react-label';
-import type { ComponentProps, ComponentState, Slot } from '@fluentui/react-utilities';
+import type { ComponentProps, ComponentState, DistributiveOmit, Slot } from '@fluentui/react-utilities';
 
 /**
  * The props added to the control inside the Field.
@@ -111,6 +111,10 @@ export type FieldState = ComponentState<Required<FieldSlots>> &
     generatedControlId: string;
   };
 
+export type FieldBaseProps = DistributiveOmit<FieldProps, 'orientation' | 'size'>;
+
+export type FieldBaseState = DistributiveOmit<FieldState, 'orientation' | 'size'>;
+
 export type FieldContextValue = Readonly<
   Pick<FieldState, 'generatedControlId' | 'orientation' | 'required' | 'size' | 'validationState'> & {
     /** The label's for prop. Undefined if there is no label. */

packages/react-components/react-field/library/src/components/Field/index.ts

@@ -1,4 +1,6 @@
 export type {
+  FieldBaseProps,
+  FieldBaseState,
   FieldContextValue,
   FieldContextValues,
   FieldControlProps,
@@ -8,5 +10,5 @@ export type {
 } from './Field.types';
 export { Field } from './Field';
 export { renderField_unstable } from './renderField';
-export { useField_unstable } from './useField';
+export { useField_unstable, useFieldBase_unstable } from './useField';
 export { fieldClassNames, useFieldStyles_unstable } from './useFieldStyles.styles';

packages/react-components/react-field/library/src/components/Field/useField.test.tsx

@@ -0,0 +1,89 @@
+import * as React from 'react';
+import { renderHook } from '@testing-library/react-hooks';
+import { useField_unstable, useFieldBase_unstable } from './useField';
+
+describe('useField_unstable', () => {
+  const ref = React.createRef<HTMLDivElement>();
+
+  it('should return default state when no props are provided', () => {
+    const { result } = renderHook(() => useField_unstable({}, ref));
+
+    expect(result.current).toMatchObject({
+      children: undefined,
+      orientation: 'vertical',
+      components: {
+        label: expect.objectContaining({}),
+      },
+      size: 'medium',
+      label: undefined,
+      validationMessageIcon: undefined,
+      validationState: 'none',
+    });
+  });
+
+  it('should return state when props are provided', () => {
+    const { result } = renderHook(() =>
+      useField_unstable(
+        {
+          orientation: 'horizontal',
+          size: 'small',
+          label: 'Test Label',
+          validationState: 'error',
+        },
+        ref,
+      ),
+    );
+
+    expect(result.current).toMatchObject({
+      orientation: 'horizontal',
+      size: 'small',
+      label: expect.objectContaining({ children: 'Test Label' }),
+      validationMessageIcon: expect.objectContaining({ children: expect.objectContaining({}) }),
+      validationState: 'error',
+    });
+  });
+});
+
+describe('useFieldBase_unstable', () => {
+  const ref = React.createRef<HTMLDivElement>();
+
+  it('should return default state when no props are provided', () => {
+    const { result } = renderHook(() => useFieldBase_unstable({}, ref));
+
+    expect(result.current).toMatchObject({
+      children: undefined,
+      components: {
+        // Plain HTML element is expected here, as base hook shouldn't know about the "styled" components
+        label: 'label',
+      },
+      validationMessage: undefined,
+      validationMessageIcon: undefined,
+      validationState: 'none',
+    });
+  });
+
+  it('should return default state when props are provided', () => {
+    const { result } = renderHook(() =>
+      useFieldBase_unstable(
+        {
+          label: 'Test Label',
+          validationMessage: 'Test Validation Message',
+          validationMessageIcon: 'Test Icon',
+          validationState: 'error',
+        },
+        ref,
+      ),
+    );
+
+    expect(result.current).toMatchObject({
+      children: undefined,
+      components: {
+        // Plain HTML element is expected here, as base hook shouldn't know about the "styled" components
+        label: 'label',
+      },
+      validationMessage: expect.objectContaining({ children: 'Test Validation Message' }),
+      validationMessageIcon: expect.objectContaining({ children: 'Test Icon' }),
+      validationState: 'error',
+    });
+  });
+});

packages/react-components/react-field/library/src/components/Field/useField.tsx

@@ -1,9 +1,11 @@
+'use client';
+
 import * as React from 'react';
 
 import { CheckmarkCircle12Filled, DiamondDismiss12Filled, Warning12Filled } from '@fluentui/react-icons';
 import { Label } from '@fluentui/react-label';
 import { getIntrinsicElementProps, useId, slot } from '@fluentui/react-utilities';
-import type { FieldProps, FieldState } from './Field.types';
+import type { FieldBaseProps, FieldBaseState, FieldProps, FieldState } from './Field.types';
 
 const validationMessageIcons = {
   error: <DiamondDismiss12Filled />,
@@ -22,13 +24,38 @@ const validationMessageIcons = {
  * @param ref - Ref to the root
  */
 export const useField_unstable = (props: FieldProps, ref: React.Ref<HTMLDivElement>): FieldState => {
-  const {
-    children,
-    orientation = 'vertical',
-    required = false,
-    validationState = props.validationMessage ? 'error' : 'none',
-    size = 'medium',
-  } = props;
+  const { orientation = 'vertical', size = 'medium', ...fieldProps } = props;
+  const state = useFieldBase_unstable(fieldProps, ref);
+
+  const defaultIcon = validationMessageIcons[state.validationState];
+
+  return {
+    ...state,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    components: { ...state.components, label: Label },
+    label: slot.optional(props.label, {
+      defaultProps: { size, ...state.label },
+      elementType: Label,
+    }),
+    validationMessageIcon: slot.optional(props.validationMessageIcon, {
+      renderByDefault: !!defaultIcon,
+      defaultProps: { children: defaultIcon },
+      elementType: 'span',
+    }),
+    orientation,
+    size,
+  };
+};
+
+/**
+ * Base hook for Field component, which manages state related to validation, ARIA attributes,
+ * ID generation, and slot structure without design props.
+ *
+ * @param props - Props passed to this field
+ * @param ref - Ref to the root
+ */
+export const useFieldBase_unstable = (props: FieldBaseProps, ref: React.Ref<HTMLDivElement>): FieldBaseState => {
+  const { children, required = false, validationState = props.validationMessage ? 'error' : 'none' } = props;
 
   const baseId = useId('field-');
   const generatedControlId = baseId + '__control';
@@ -37,8 +64,8 @@ export const useField_unstable = (props: FieldProps, ref: React.Ref<HTMLDivEleme
     elementType: 'div',
   });
   const label = slot.optional(props.label, {
-    defaultProps: { htmlFor: generatedControlId, id: baseId + '__label', required, size },
-    elementType: Label,
+    defaultProps: { htmlFor: generatedControlId, id: baseId + '__label', required },
+    elementType: 'label',
   });
   const validationMessage = slot.optional(props.validationMessage, {
     defaultProps: {
@@ -48,21 +75,17 @@ export const useField_unstable = (props: FieldProps, ref: React.Ref<HTMLDivEleme
     elementType: 'div',
   });
   const hint = slot.optional(props.hint, { defaultProps: { id: baseId + '__hint' }, elementType: 'div' });
-  const defaultIcon = validationMessageIcons[validationState];
   const validationMessageIcon = slot.optional(props.validationMessageIcon, {
-    renderByDefault: !!defaultIcon,
-    defaultProps: { children: defaultIcon },
+    renderByDefault: false,
     elementType: 'span',
   });
 
   return {
     children,
     generatedControlId,
-    orientation,
     required,
-    size,
     validationState,
-    components: { root: 'div', label: Label, validationMessage: 'div', validationMessageIcon: 'span', hint: 'div' },
+    components: { root: 'div', label: 'label', validationMessage: 'div', validationMessageIcon: 'span', hint: 'div' },
     root,
     label,
     validationMessageIcon,

packages/react-components/react-field/library/src/index.ts

@@ -14,3 +14,7 @@ export {
   useFieldControlProps_unstable,
 } from './contexts/index';
 export type { FieldControlPropsOptions } from './contexts/index';
+
+// Experimental APIs - will be uncommented in the experimental release branch
+// export { useFieldBase_unstable } from './Field';
+// export type { FieldBaseProps, FieldBaseState } from './Field';