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.tsx

@@ -1,9 +1,11 @@
+'use client';
+
 import * as React from 'react';
 
 import { CheckmarkCircle12Filled, ErrorCircle12Filled, 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: <ErrorCircle12Filled />,
@@ -22,13 +24,29 @@ 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);
+
+  // Merge the size design prop into the label slot (which already has htmlFor, id, required)
+  const label = state.label ? { ...state.label, size } : state.label;
+
+  return {
+    ...state,
+    label,
+    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,7 +55,7 @@ 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 },
+    defaultProps: { htmlFor: generatedControlId, id: baseId + '__label', required },
     elementType: Label,
   });
   const validationMessage = slot.optional(props.validationMessage, {
@@ -58,9 +76,7 @@ export const useField_unstable = (props: FieldProps, ref: React.Ref<HTMLDivEleme
   return {
     children,
     generatedControlId,
-    orientation,
     required,
-    size,
     validationState,
     components: { root: 'div', label: Label, validationMessage: 'div', validationMessageIcon: 'span', hint: 'div' },
     root,

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';