feat(WCAG): Associate field descriptions to inputs

packages/@sanity/portable-text-editor/src/editor/Editable.tsx

@@ -67,6 +67,7 @@ export type PortableTextEditableProps = {
   scrollSelectionIntoView?: ScrollSelectionIntoViewFunction
   selection?: EditorSelection
   spellCheck?: boolean
+  describedBy?: string
 }
 
 /**
@@ -91,6 +92,7 @@ export const PortableTextEditable = forwardRef(function PortableTextEditable(
     selection: propsSelection,
     scrollSelectionIntoView,
     spellCheck,
+    describedBy,
     ...restProps
   } = props
 
@@ -405,6 +407,7 @@ export const PortableTextEditable = forwardRef(function PortableTextEditable(
         renderLeaf={renderLeaf}
         style={props.style}
         scrollSelectionIntoView={scrollSelectionIntoViewToSlate}
+        aria-describedby={describedBy}
       />
     ),
     [
@@ -420,6 +423,7 @@ export const PortableTextEditable = forwardRef(function PortableTextEditable(
       renderElement,
       renderLeaf,
       scrollSelectionIntoViewToSlate,
+      describedBy,
     ],
   )
 

packages/@sanity/portable-text-editor/src/editor/__tests__/PortableTextEditor.test.tsx

@@ -38,6 +38,7 @@ describe('initialization', () => {
         <div>
           <div>
             <div
+              aria-describedby="desc_foo"
               aria-multiline="true"
               autocapitalize="false"
               autocorrect="false"

packages/@sanity/portable-text-editor/src/editor/__tests__/PortableTextEditorTester.tsx

@@ -73,6 +73,7 @@ export const PortableTextEditorTester = forwardRef(function PortableTextEditorTe
       <PortableTextEditable
         selection={props.selection || undefined}
         renderPlaceholder={props.renderPlaceholder}
+        describedBy="desc_foo"
       />
     </PortableTextEditor>
   )

packages/sanity/src/core/form/components/formField/FormFieldHeaderText.tsx

@@ -3,6 +3,7 @@
 import {FormNodeValidation} from '@sanity/types'
 import {Box, Flex, Stack, Text} from '@sanity/ui'
 import React, {memo} from 'react'
+import {constructDescriptionId} from '../../members/common/constructDescriptionId'
 import {FormFieldValidationStatus} from './FormFieldValidationStatus'
 
 /** @internal */
@@ -45,7 +46,7 @@ export const FormFieldHeaderText = memo(function FormFieldHeaderText(
       </Flex>
 
       {description && (
-        <Text muted size={1}>
+        <Text muted size={1} id={constructDescriptionId(inputId, description)}>
           {description}
         </Text>
       )}

packages/sanity/src/core/form/components/formField/FormFieldSet.tsx

@@ -6,6 +6,7 @@ import {FormNodeValidation} from '@sanity/types'
 import {FormNodePresence} from '../../../presence'
 import {DocumentFieldActionNode} from '../../../config'
 import {useFieldActions} from '../../field'
+import {constructDescriptionId} from '../../members/common/constructDescriptionId'
 import {FormFieldValidationStatus} from './FormFieldValidationStatus'
 import {FormFieldSetLegend} from './FormFieldSetLegend'
 import {focusRingStyle} from './styles'
@@ -43,6 +44,7 @@ export interface FormFieldSetProps {
    * @beta
    */
   validation?: FormNodeValidation[]
+  inputId: string
 }
 
 function getChildren(children: React.ReactNode | (() => React.ReactNode)): React.ReactNode {
@@ -109,6 +111,7 @@ export const FormFieldSet = forwardRef(function FormFieldSet(
     tabIndex,
     title,
     validation = EMPTY_ARRAY,
+    inputId,
     ...restProps
   } = props
 
@@ -170,7 +173,7 @@ export const FormFieldSet = forwardRef(function FormFieldSet(
             </Flex>
 
             {description && (
-              <Text muted size={1}>
+              <Text muted size={1} id={constructDescriptionId(inputId, description)}>
                 {description}
               </Text>
             )}

packages/sanity/src/core/form/inputs/PortableText/Compositor.tsx

@@ -351,10 +351,11 @@ export function Compositor(props: Omit<InputProps, 'schemaType' | 'arrayFunction
       renderPreview,
     ],
   )
-
+  const describedBy = props.elementProps['aria-describedby']
   const editorNode = useMemo(
     () => (
       <Editor
+        describedBy={describedBy}
         hasFocus={hasFocus}
         hotkeys={editorHotkeys}
         isActive={isActive}
@@ -390,6 +391,7 @@ export function Compositor(props: Omit<InputProps, 'schemaType' | 'arrayFunction
       onPaste,
       path,
       readOnly,
+      describedBy,
     ],
   )
 

packages/sanity/src/core/form/inputs/PortableText/Editor.tsx

@@ -51,6 +51,7 @@ interface EditorProps {
   scrollElement: HTMLElement | null
   setPortalElement?: (portalElement: HTMLDivElement | null) => void
   setScrollElement: (scrollElement: HTMLElement | null) => void
+  describedBy: string | undefined
 }
 
 const renderDecorator: RenderDecoratorFunction = (props) => {
@@ -84,6 +85,7 @@ export function Editor(props: EditorProps) {
     scrollElement,
     setPortalElement,
     setScrollElement,
+    describedBy,
   } = props
   const {isTopLayer} = useLayer()
   const editableRef = useRef<HTMLDivElement | null>(null)
@@ -148,6 +150,7 @@ export function Editor(props: EditorProps) {
         selection={initialSelection}
         style={noOutlineStyle}
         spellCheck={spellcheck}
+        describedBy={describedBy}
       />
     ),
     [
@@ -161,6 +164,7 @@ export function Editor(props: EditorProps) {
       renderPlaceholder,
       scrollSelectionIntoView,
       spellcheck,
+      describedBy,
     ],
   )
 

packages/sanity/src/core/form/inputs/ReferenceInput/ReferenceField.tsx

@@ -300,6 +300,7 @@ export function ReferenceField(props: ReferenceFieldProps) {
         level={props.level}
         title={props.title}
         validation={props.validation}
+        inputId={props.inputId}
       >
         {isEditing ? (
           <Box>{children}</Box>

packages/sanity/src/core/form/inputs/ReferenceInput/ReferenceItem.tsx

@@ -369,6 +369,7 @@ export function ReferenceItem<Item extends ReferenceItemValue = ReferenceItemVal
               description={schemaType.description}
               __unstable_presence={presence}
               validation={validation}
+              inputId={inputId}
             >
               {children}
             </FormFieldSet>

packages/sanity/src/core/form/members/array/items/ArrayOfObjectsItem.tsx

@@ -23,6 +23,7 @@ import {createProtoValue} from '../../../utils/createProtoValue'
 import {isEmptyItem} from '../../../store/utils/isEmptyItem'
 import {useResolveInitialValueForType} from '../../../../store'
 import {resolveInitialArrayValues} from '../../common/resolveInitialArrayValues'
+import {constructDescriptionId} from '../../common/constructDescriptionId'
 
 /**
  *
@@ -242,8 +243,12 @@ export function ArrayOfObjectsItem(props: MemberItemProps) {
       onFocus: handleFocus,
       id: member.item.id,
       ref: focusRef,
+      'aria-describedby': constructDescriptionId(
+        member.item.id,
+        member.item.schemaType.description,
+      ),
     }),
-    [handleBlur, handleFocus, member.item.id],
+    [handleBlur, handleFocus, member.item.id, member.item.schemaType.description],
   )
 
   const inputProps = useMemo((): Omit<ObjectInputProps, 'renderDefault'> => {

packages/sanity/src/core/form/members/array/items/ArrayOfPrimitivesItem.tsx

@@ -13,6 +13,7 @@ import {
 import {insert, PatchArg, PatchEvent, set, unset} from '../../../patch'
 import {useFormCallbacks} from '../../../studio/contexts/FormCallbacks'
 import {resolveNativeNumberInputValue} from '../../common/resolveNativeNumberInputValue'
+import {constructDescriptionId} from '../../common/constructDescriptionId'
 
 /**
  *
@@ -111,6 +112,10 @@ export function ArrayOfPrimitivesItem(props: PrimitiveMemberItemProps) {
       value: resolveNativeInputValue(member.item.schemaType, member.item.value, localValue),
       readOnly: Boolean(member.item.readOnly),
       placeholder: member.item.schemaType.placeholder,
+      'aria-describedby': constructDescriptionId(
+        member.item.id,
+        member.item.schemaType.description,
+      ),
     }),
     [
       handleBlur,

packages/sanity/src/core/form/members/common/constructDescriptionId.ts

@@ -0,0 +1,14 @@
+import React from 'react'
+
+/**
+ * Creates a description id from a field id, for use with aria-describedby in the field,
+ * and added to the descriptive element id.
+ * @internal
+ */
+export function constructDescriptionId(
+  id: string | undefined,
+  description: React.ReactNode | undefined,
+): string | undefined {
+  if (!description || !id) return undefined
+  return `desc_${id}`
+}

packages/sanity/src/core/form/members/object/MemberFieldset.tsx

@@ -57,6 +57,7 @@ export const MemberFieldSet = memo(function MemberFieldSet(props: {
       onExpand={handleExpand}
       columns={member?.fieldSet?.columns}
       data-testid={`fieldset-${member.fieldSet.name}`}
+      inputId={member.fieldSet.name}
     >
       {member.fieldSet.members.map((fieldsetMember) => {
         if (fieldsetMember.kind === 'error') {

packages/sanity/src/core/form/members/object/fields/ArrayOfObjectsField.tsx

@@ -34,6 +34,7 @@ import {resolveInitialArrayValues} from '../../common/resolveInitialArrayValues'
 import {applyAll} from '../../../patch/applyPatch'
 import {useFormPublishedId} from '../../../useFormPublishedId'
 import {DocumentFieldActionNode} from '../../../../config'
+import {constructDescriptionId} from '../../common/constructDescriptionId'
 
 /**
  * Responsible for creating inputProps and fieldProps to pass to ´renderInput´ and ´renderField´ for an array input
@@ -298,8 +299,12 @@ export function ArrayOfObjectsField(props: {
       onFocus: handleFocus,
       id: member.field.id,
       ref: focusRef,
+      'aria-describedby': constructDescriptionId(
+        member.field.id,
+        member.field.schemaType.description,
+      ),
     }),
-    [handleBlur, handleFocus, member.field.id],
+    [handleBlur, handleFocus, member.field.id, member.field.schemaType.description],
   )
 
   const client = useClient(DEFAULT_STUDIO_CLIENT_OPTIONS)

packages/sanity/src/core/form/members/object/fields/ArrayOfPrimitivesField.tsx

@@ -36,6 +36,7 @@ import {readAsText} from '../../../studio/uploads/file/readAsText'
 import {accepts} from '../../../studio/uploads/accepts'
 import {applyAll} from '../../../patch/applyPatch'
 import {useFormBuilder} from '../../../useFormBuilder'
+import {constructDescriptionId} from '../../common/constructDescriptionId'
 
 function move<T>(arr: T[], from: number, to: number): T[] {
   const copy = arr.slice()
@@ -301,8 +302,12 @@ export function ArrayOfPrimitivesField(props: {
       onFocus: handleFocus,
       id: member.field.id,
       ref: focusRef,
+      'aria-describedby': constructDescriptionId(
+        member.field.id,
+        member.field.schemaType.description,
+      ),
     }),
-    [handleBlur, handleFocus, member.field.id],
+    [handleBlur, handleFocus, member.field.id, member.field.schemaType.description],
   )
 
   const plainTextUploader = useMemo(

packages/sanity/src/core/form/members/object/fields/ObjectField.tsx

@@ -19,6 +19,7 @@ import {FormCallbacksProvider, useFormCallbacks} from '../../../studio/contexts/
 import {createProtoValue} from '../../../utils/createProtoValue'
 import {applyAll} from '../../../patch/applyPatch'
 import {useFormBuilder} from '../../../useFormBuilder'
+import {constructDescriptionId} from '../../common/constructDescriptionId'
 
 /**
  * Responsible for creating inputProps and fieldProps to pass to ´renderInput´ and ´renderField´ for an object input
@@ -183,8 +184,12 @@ export const ObjectField = function ObjectField(props: {
       onFocus: handleFocus,
       id: member.field.id,
       ref: focusRef,
+      'aria-describedby': constructDescriptionId(
+        member.field.id,
+        member.field.schemaType.description,
+      ),
     }),
-    [handleBlur, handleFocus, member.field.id],
+    [handleBlur, handleFocus, member.field.id, member.field.schemaType.description],
   )
 
   const inputProps = useMemo((): Omit<ObjectInputProps, 'renderDefault'> => {

packages/sanity/src/core/form/members/object/fields/PrimitiveField.tsx

@@ -11,6 +11,7 @@ import {FormPatch, PatchEvent, set, unset} from '../../../patch'
 import {useFormCallbacks} from '../../../studio/contexts/FormCallbacks'
 import {resolveNativeNumberInputValue} from '../../common/resolveNativeNumberInputValue'
 import {useFormBuilder} from '../../../useFormBuilder'
+import {constructDescriptionId} from '../../common/constructDescriptionId'
 
 /**
  * Responsible for creating inputProps and fieldProps to pass to ´renderInput´ and ´renderField´ for a primitive field/input
@@ -105,6 +106,10 @@ export function PrimitiveField(props: {
       value: resolveNativeNumberInputValue(member.field.schemaType, member.field.value, localValue),
       readOnly: Boolean(member.field.readOnly),
       placeholder: member.field.schemaType.placeholder,
+      'aria-describedby': constructDescriptionId(
+        member.field.id,
+        member.field.schemaType.description,
+      ),
     }),
     [
       handleBlur,

packages/sanity/src/core/form/studio/FormBuilder.tsx

@@ -177,7 +177,13 @@ function RootInput() {
 
   const rootInputProps: Omit<ObjectInputProps, 'renderDefault'> = {
     focusPath,
-    elementProps: {ref: focusRef, id, onBlur: handleBlur, onFocus: handleFocus},
+    elementProps: {
+      ref: focusRef,
+      id,
+      onBlur: handleBlur,
+      onFocus: handleFocus,
+      'aria-describedby': undefined, // Root input should not have any aria-describedby
+    },
     changed: members.some((m) => m.kind === 'field' && m.field.changed),
     focused,
     groups,

packages/sanity/src/core/form/studio/inputResolver/fieldResolver.tsx

@@ -105,6 +105,7 @@ function ObjectOrArrayField(field: ObjectFieldProps | ArrayFieldProps) {
           onExpand={field.onExpand}
           title={field.title}
           validation={field.validation}
+          inputId={field.inputId}
         >
           {field.children}
         </FormFieldSet>
@@ -152,6 +153,7 @@ function ImageOrFileField(field: ObjectFieldProps) {
           onExpand={field.onExpand}
           title={field.title}
           validation={field.validation}
+          inputId={field.inputId}
         >
           {field.children}
         </FormFieldSet>

packages/sanity/src/core/form/types/inputProps.ts

@@ -392,6 +392,7 @@ export interface PrimitiveInputElementProps {
   onFocus: FocusEventHandler
   onBlur: FocusEventHandler
   ref: React.MutableRefObject<any>
+  'aria-describedby': string | undefined
 }
 
 /**
@@ -402,6 +403,7 @@ export interface ComplexElementProps {
   onFocus: FocusEventHandler
   onBlur: FocusEventHandler
   ref: React.MutableRefObject<any>
+  'aria-describedby': string | undefined
 }
 
 /**