feat(WCAG): Associate field descriptions to inputs (#4896)

* feat(WCAG): Associate field descriptions to inputs * feat(WCAG): Adds aria-describedby to PTE * feat(WCAG): Rename PT prop and change constructDescriptionId for createDescriptionId * fix(portable-text-editor): forward html attributes to editable component This will forward html props for the editable element to the slate editable. It will also get rid of the need of having an own wrapper div element to put the ref on. Point it directly on the editable element. * test(portable-text-editor): update snapshot * refactor(portable-text-editor): remove unnecessary memo This doesn't need to be memoed, at least not after supporting restProps here. Debugging shows that the nodes inside are not re-rendered by removing this memo, which is what we care about. --------- Co-authored-by: Per-Kristian Nordnes <per.kristian.nordnes@gmail.com>
sanity-io · Sep 13, 2023 · e7a8e32 · e7a8e32 · vercel · Sep 13, 2023
1 parent a94680b
commit e7a8e32
Show file tree

Hide file tree

Showing 20 changed files with 132 additions and 95 deletions.
diff --git a/packages/@sanity/portable-text-editor/src/editor/Editable.tsx b/packages/@sanity/portable-text-editor/src/editor/Editable.tsx
@@ -52,7 +52,10 @@ const EMPTY_DECORATORS: BaseRange[] = []
 /**
  * @public
  */
-export type PortableTextEditableProps = {
+export type PortableTextEditableProps = Omit<
+  React.TextareaHTMLAttributes<HTMLDivElement>,
+  'onPaste' | 'onCopy'
+> & {
   hotkeys?: HotkeyOptions
   onBeforeInput?: OnBeforeInputFn
   onPaste?: OnPasteFn
@@ -387,48 +390,33 @@ export const PortableTextEditable = forwardRef(function PortableTextEditable(
     return EMPTY_DECORATORS
   }, [schemaTypes, slateEditor])
 
-  // The editor
-  const slateEditable = useMemo(
-    () => (
-      <SlateEditable
-        autoFocus={false}
-        className="pt-editable"
-        decorate={decorate}
-        onBlur={handleOnBlur}
-        onCopy={handleCopy}
-        onDOMBeforeInput={handleOnBeforeInput}
-        onFocus={handleOnFocus}
-        onKeyDown={handleKeyDown}
-        onPaste={handlePaste}
-        readOnly={readOnly}
-        renderElement={renderElement}
-        renderLeaf={renderLeaf}
-        style={props.style}
-        scrollSelectionIntoView={scrollSelectionIntoViewToSlate}
-      />
-    ),
-    [
-      decorate,
-      handleCopy,
-      handleKeyDown,
-      handleOnBeforeInput,
-      handleOnBlur,
-      handleOnFocus,
-      handlePaste,
-      props.style,
-      readOnly,
-      renderElement,
-      renderLeaf,
-      scrollSelectionIntoViewToSlate,
-    ],
-  )
+  // Set the forwarded ref to be the Slate editable DOM element
+  useEffect(() => {
+    ref.current = ReactEditor.toDOMNode(slateEditor, slateEditor) as HTMLDivElement | null
+  }, [slateEditor, ref])
 
   if (!portableTextEditor) {
     return null
   }
-  return (
-    <div ref={ref} {...restProps}>
-      {hasInvalidValue ? null : slateEditable}
-    </div>
+  return hasInvalidValue ? null : (
+    <SlateEditable
+      {...restProps}
+      autoFocus={false}
+      className={restProps.className || 'pt-editable'}
+      decorate={decorate}
+      onBlur={handleOnBlur}
+      onCopy={handleCopy}
+      onDOMBeforeInput={handleOnBeforeInput}
+      onFocus={handleOnFocus}
+      onKeyDown={handleKeyDown}
+      onPaste={handlePaste}
+      readOnly={readOnly}
+      // We have implemented our own placeholder logic with decorations.
+      // This 'renderPlaceholder' should not be used.
+      renderPlaceholder={undefined}
+      renderElement={renderElement}
+      renderLeaf={renderLeaf}
+      scrollSelectionIntoView={scrollSelectionIntoViewToSlate}
+    />
   )
 })
diff --git a/packages/@sanity/portable-text-editor/src/editor/__tests__/PortableTextEditor.test.tsx b/packages/@sanity/portable-text-editor/src/editor/__tests__/PortableTextEditor.test.tsx
@@ -35,57 +35,56 @@ describe('initialization', () => {
       expect(onChange).toHaveBeenCalledWith({type: 'ready'})
       expect(onChange).toHaveBeenCalledWith({type: 'value', value: undefined})
       expect(container).toMatchInlineSnapshot(`
+<div>
+  <div
+    aria-describedby="desc_foo"
+    aria-multiline="true"
+    autocapitalize="false"
+    autocorrect="false"
+    class="pt-editable"
+    contenteditable="true"
+    data-slate-editor="true"
+    data-slate-node="value"
+    role="textbox"
+    spellcheck="false"
+    style="position: relative; white-space: pre-wrap; word-wrap: break-word;"
+    zindex="-1"
+  >
+    <div
+      class="pt-block pt-text-block pt-text-block-style-normal"
+      data-slate-node="element"
+    >
+      <div
+        draggable="false"
+      >
         <div>
-          <div>
-            <div
-              aria-multiline="true"
-              autocapitalize="false"
-              autocorrect="false"
-              class="pt-editable"
-              contenteditable="true"
-              data-slate-editor="true"
-              data-slate-node="value"
-              role="textbox"
-              spellcheck="false"
-              style="position: relative; white-space: pre-wrap; word-wrap: break-word;"
-              zindex="-1"
+          <span
+            data-slate-node="text"
+          >
+            <span
+              contenteditable="false"
+              style="opacity: 0.5; position: absolute; user-select: none; pointer-events: none;"
             >
-              <div
-                class="pt-block pt-text-block pt-text-block-style-normal"
-                data-slate-node="element"
+              Jot something down here
+            </span>
+            <span
+              data-slate-leaf="true"
+            >
+              <span
+                data-slate-length="0"
+                data-slate-zero-width="n"
               >
-                <div
-                  draggable="false"
-                >
-                  <div>
-                    <span
-                      data-slate-node="text"
-                    >
-                      <span
-                        contenteditable="false"
-                        style="opacity: 0.5; position: absolute; user-select: none; pointer-events: none;"
-                      >
-                        Jot something down here
-                      </span>
-                      <span
-                        data-slate-leaf="true"
-                      >
-                        <span
-                          data-slate-length="0"
-                          data-slate-zero-width="n"
-                        >
-                          
-                          <br />
-                        </span>
-                      </span>
-                    </span>
-                  </div>
-                </div>
-              </div>
-            </div>
-          </div>
+                
+                <br />
+              </span>
+            </span>
+          </span>
         </div>
-      `)
+      </div>
+    </div>
+  </div>
+</div>
+`)
     })
   })
   it('takes value from props', async () => {

diff --git a/packages/@sanity/portable-text-editor/src/editor/__tests__/PortableTextEditorTester.tsx b/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}
+        aria-describedby="desc_foo"
       />
     </PortableTextEditor>
   )

diff --git a/packages/sanity/src/core/form/components/formField/FormFieldHeaderText.tsx b/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 {createDescriptionId} from '../../members/common/createDescriptionId'
 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={createDescriptionId(inputId, description)}>
           {description}
         </Text>
       )}

diff --git a/packages/sanity/src/core/form/components/formField/FormFieldSet.tsx b/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 {createDescriptionId} from '../../members/common/createDescriptionId'
 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={createDescriptionId(inputId, description)}>
                 {description}
               </Text>
             )}

diff --git a/packages/sanity/src/core/form/inputs/PortableText/Compositor.tsx b/packages/sanity/src/core/form/inputs/PortableText/Compositor.tsx
@@ -351,10 +351,11 @@ export function Compositor(props: Omit<InputProps, 'schemaType' | 'arrayFunction
       renderPreview,
     ],
   )
-
+  const ariaDescribedBy = props.elementProps['aria-describedby']
   const editorNode = useMemo(
     () => (
       <Editor
+        ariaDescribedBy={ariaDescribedBy}
         hasFocus={hasFocus}
         hotkeys={editorHotkeys}
         isActive={isActive}
@@ -390,6 +391,7 @@ export function Compositor(props: Omit<InputProps, 'schemaType' | 'arrayFunction
       onPaste,
       path,
       readOnly,
+      ariaDescribedBy,
     ],
   )
 

diff --git a/packages/sanity/src/core/form/inputs/PortableText/Editor.tsx b/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
+  ariaDescribedBy: string | undefined
 }
 
 const renderDecorator: RenderDecoratorFunction = (props) => {
@@ -84,6 +85,7 @@ export function Editor(props: EditorProps) {
     scrollElement,
     setPortalElement,
     setScrollElement,
+    ariaDescribedBy,
   } = 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}
+        aria-describedby={ariaDescribedBy}
       />
     ),
     [
@@ -161,6 +164,7 @@ export function Editor(props: EditorProps) {
       renderPlaceholder,
       scrollSelectionIntoView,
       spellcheck,
+      ariaDescribedBy,
     ],
   )
 

diff --git a/packages/sanity/src/core/form/inputs/ReferenceInput/ReferenceField.tsx b/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>

diff --git a/packages/sanity/src/core/form/inputs/ReferenceInput/ReferenceItem.tsx b/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>

diff --git a/packages/sanity/src/core/form/members/array/items/ArrayOfObjectsItem.tsx b/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 {createDescriptionId} from '../../common/createDescriptionId'
 
 /**
  *
@@ -242,8 +243,9 @@ export function ArrayOfObjectsItem(props: MemberItemProps) {
       onFocus: handleFocus,
       id: member.item.id,
       ref: focusRef,
+      'aria-describedby': createDescriptionId(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'> => {

diff --git a/packages/sanity/src/core/form/members/array/items/ArrayOfPrimitivesItem.tsx b/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 {createDescriptionId} from '../../common/createDescriptionId'
 
 /**
  *
@@ -111,6 +112,7 @@ 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': createDescriptionId(member.item.id, member.item.schemaType.description),
     }),
     [
       handleBlur,

diff --git a/packages/sanity/src/core/form/members/common/createDescriptionId.ts b/packages/sanity/src/core/form/members/common/createDescriptionId.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 createDescriptionId(
+  id: string | undefined,
+  description: React.ReactNode | undefined,
+): string | undefined {
+  if (!description || !id) return undefined
+  return `desc_${id}`
+}
diff --git a/packages/sanity/src/core/form/members/object/MemberFieldset.tsx b/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') {

diff --git a/packages/sanity/src/core/form/members/object/fields/ArrayOfObjectsField.tsx b/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 {createDescriptionId} from '../../common/createDescriptionId'
 
 /**
  * Responsible for creating inputProps and fieldProps to pass to ´renderInput´ and ´renderField´ for an array input
@@ -298,8 +299,9 @@ export function ArrayOfObjectsField(props: {
       onFocus: handleFocus,
       id: member.field.id,
       ref: focusRef,
+      'aria-describedby': createDescriptionId(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)