@coopdigital/react 1.27.2 → 1.28.0

package/src/components/Field/Field.tsx

@@ -5,13 +5,14 @@ import clsx from "clsx"
 import React from "react"
 
 import { Error as BaseError, type ErrorProps } from "@/components/FieldMarkers/Error"
+import { getMarkerIds, type Markers } from "@/components/FieldMarkers/fieldmarkers-utils"
 import { Hint as BaseHint, type HintProps } from "@/components/FieldMarkers/Hint"
 import { Label as BaseLabel, type LabelProps } from "@/components/FieldMarkers/Label"
+import { useFieldset } from "@/components/Fieldset/Fieldset.context"
 import { useId } from "@/hooks/useId"
-import { SlotConfig } from "@/types"
-import { getSlotProp } from "@/utils"
+import { forEachSlot, getSlotProp } from "@/utils"
 
-import { FieldConfig, FieldContext } from "./Field.context"
+import { FieldConfig, FieldContext, useField } from "./Field.context"
 
 interface FieldProps extends HTMLAttributes<HTMLDivElement> {
   /** Specify whether the Field should render inside a box. */
@@ -22,7 +23,7 @@ interface FieldProps extends HTMLAttributes<HTMLDivElement> {
   children?: React.ReactNode
   /** Specify additional CSS classes. */
   classname?: string
-  /** Specify the component error state. */
+  /** Specify the component error state. Inherits the error state of a Fieldset with `group` set when not specified. */
   error?: boolean
   /** Specify whether the Field should show the left-hand error bar if it is in an error state. */
   hideErrorBar?: boolean
@@ -34,32 +35,38 @@ const Field = ({
   boxed = false,
   children,
   className,
-  error = false,
+  error: errorProp,
   hideErrorBar = false,
   ref,
   ...props
 }: FieldProps): JSX.Element => {
   const internalId = useId()
+  const fieldset = useFieldset()
+  const error = errorProp ?? fieldset?.error ?? false
 
   const controlProps: FieldConfig = {
     disabled: false,
     id: internalId,
   }
 
-  Array.from([children].flat()).forEach((child: React.ReactNode) => {
-    if (child && typeof child === "object" && "type" in child) {
-      if (typeof child?.type === "function" && "slot" in child.type) {
-        const { slot } = child.type as { slot: SlotConfig }
-        if (slot.field && child.props) {
-          controlProps.inline = slot.inline ?? false
-          controlProps.disabled = getSlotProp<boolean>(child, "disabled") ?? false
-          controlProps.id = getSlotProp<string>(child, "id") ?? controlProps.id
-          controlProps.suffix = slot.suffix ?? undefined
-        }
-      }
+  // The Hint and Error rendered in the Field, for the aria-describedby of the control
+  const markers: Markers = {}
+
+  forEachSlot(children, (slot, child) => {
+    if (slot.field) {
+      controlProps.inline = slot.inline ?? false
+      controlProps.disabled = getSlotProp<boolean>(child, "disabled") ?? false
+      controlProps.id = getSlotProp<string>(child, "id") ?? controlProps.id
+      controlProps.suffix = slot.suffix ?? undefined
+    } else if (slot.name === "FieldHint") {
+      markers.hint = { id: getSlotProp<string>(child, "id") }
+    } else if (slot.name === "FieldError") {
+      markers.error = { id: getSlotProp<string>(child, "id") }
     }
   })
 
+  const markerIds = getMarkerIds(markers, controlProps.id)
+
   const componentProps = {
     ...props,
     "aria-disabled": controlProps.disabled || undefined,
@@ -70,7 +77,7 @@ const Field = ({
   }
 
   return (
-    <FieldContext.Provider value={{ ...controlProps }}>
+    <FieldContext.Provider value={{ ...controlProps, ...markerIds, error }}>
       <div {...componentProps} ref={ref}>
         {children}
       </div>
@@ -78,9 +85,21 @@ const Field = ({
   )
 }
 
-const FieldLabel = (props: LabelProps): JSX.Element => <BaseLabel {...props} />
-const FieldHint = (props: HintProps): JSX.Element => <BaseHint {...props} />
-const FieldError = (props: ErrorProps): JSX.Element => <BaseError {...props} />
+const FieldLabel = (props: LabelProps): JSX.Element => {
+  const field = useField()
+
+  return (
+    <BaseLabel
+      htmlFor={field ? field.id + (field.suffix ?? "") : undefined}
+      id={field ? `${field.id}_label` : undefined}
+      {...props}
+    />
+  )
+}
+const FieldHint = (props: HintProps): JSX.Element => <BaseHint id={useField()?.hintId} {...props} />
+const FieldError = (props: ErrorProps): JSX.Element => (
+  <BaseError id={useField()?.errorId} {...props} />
+)
 
 Field.slot = { name: "Field" }
 FieldLabel.slot = { name: "FieldLabel" }

package/src/components/FieldMarkers/Error.tsx

@@ -18,7 +18,8 @@ export const Error = ({ children, className, ref, ...props }: ErrorProps): JSX.E
   }
   return (
     <span {...componentProps} ref={ref}>
-      {children}
+      {/* Tell screen reader users this is an error, not a hint, when it describes a control */}
+      <span className="sr-only">Error:</span> {children}
     </span>
   )
 }

package/src/components/FieldMarkers/Label.tsx

@@ -1,8 +1,6 @@
 import clsx from "clsx"
 import { JSX, LabelHTMLAttributes, Ref } from "react"
 
-import { useField } from "@/components/Field/Field.context"
-
 export interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
   /** Content inside the component. */
   children?: React.ReactNode
@@ -17,17 +15,12 @@ export interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
 export const Label = ({
   children,
   className,
-  htmlFor,
-  id,
   isVisible = true,
   ref,
   ...props
 }: LabelProps): JSX.Element => {
-  const field = useField()
   const componentProps = {
     className: clsx("coop-field-label", !isVisible && "sr-only", className),
-    htmlFor: htmlFor ?? (field?.id ? field.id + (field?.suffix ?? "") : undefined),
-    id: id ?? (field?.id ? field.id + "_label" : undefined),
     ...props,
   }
   return (

package/src/components/FieldMarkers/fieldmarkers-utils.ts

@@ -0,0 +1,26 @@
+export interface Markers {
+  error?: { id?: string }
+  hint?: { id?: string }
+}
+
+export interface MarkerIds {
+  describedBy?: string
+  errorId: string
+  hintId: string
+}
+
+// Join ids for aria-describedby, skipping empties
+export const joinIds = (...ids: (string | false | undefined)[]): string | undefined =>
+  ids.filter(Boolean).join(" ") || undefined
+
+// Get the ids for a Field or Fieldset hint and error
+export const getMarkerIds = (markers: Markers, baseId: string): MarkerIds => {
+  const hintId = markers.hint?.id ?? `${baseId}_hint`
+  const errorId = markers.error?.id ?? `${baseId}_error`
+
+  return {
+    describedBy: joinIds(markers.hint && hintId, markers.error && errorId),
+    errorId,
+    hintId,
+  }
+}

package/src/components/Fieldset/Fieldset.context.ts

@@ -0,0 +1,13 @@
+"use client"
+import { createContext, useContext } from "react"
+
+export interface FieldsetContextValue {
+  /** The error state passed down to Fields when the Fieldset is a group. */
+  error?: boolean
+  errorId?: string
+  hintId?: string
+}
+
+export const FieldsetContext = createContext<FieldsetContextValue | null>(null)
+
+export const useFieldset = () => useContext(FieldsetContext)

package/src/components/Fieldset/Fieldset.tsx

@@ -1,9 +1,15 @@
+"use client"
 import clsx from "clsx"
 import { type FieldsetHTMLAttributes, HTMLAttributes, type JSX, Ref } from "react"
 
 import { Error as BaseError, type ErrorProps } from "@/components/FieldMarkers/Error"
+import { getMarkerIds, joinIds, type Markers } from "@/components/FieldMarkers/fieldmarkers-utils"
 import { Hint as BaseHint, type HintProps } from "@/components/FieldMarkers/Hint"
 import { Legend as BaseLegend, type LegendProps } from "@/components/FieldMarkers/Legend"
+import { useId } from "@/hooks/useId"
+import { forEachSlot, getSlotProp } from "@/utils"
+
+import { FieldsetContext, useFieldset } from "./Fieldset.context"
 
 export interface FieldsetProps extends FieldsetHTMLAttributes<HTMLFieldSetElement> {
   /** Content inside the component.
@@ -16,33 +22,57 @@ export interface FieldsetProps extends FieldsetHTMLAttributes<HTMLFieldSetElemen
   disabled?: boolean
   /** Specify the component error state. */
   error?: boolean
+  /** Specify whether the Fieldset is a single question, such as a group of Radio inputs. Fields inside inherit its error state. */
+  group?: boolean
   /** Specify whether the Fieldset should show the left-hand error bar if it is in an error state. */
   hideErrorBar?: boolean
   /** Specify a custom React ref for this component. */
   ref?: Ref<HTMLFieldSetElement>
 }
 const Fieldset = ({
+  "aria-describedby": ariaDescribedBy,
   children,
   className,
   disabled,
   error = false,
+  group = false,
   hideErrorBar = false,
+  id,
   ref,
   ...props
 }: FieldsetProps): JSX.Element => {
+  const uid = useId(id)
+
+  // The Hint and Error rendered in the Fieldset, for aria-describedby
+  const markers: Markers = {}
+
+  forEachSlot(children, (slot, child) => {
+    if (slot.name === "FieldsetHint") {
+      markers.hint = { id: getSlotProp<string>(child, "id") }
+    } else if (slot.name === "FieldsetError") {
+      markers.error = { id: getSlotProp<string>(child, "id") }
+    }
+  })
+
+  const { describedBy, errorId, hintId } = getMarkerIds(markers, uid)
+
   const componentProps = {
+    "aria-describedby": joinIds(describedBy, ariaDescribedBy),
     "aria-disabled": disabled,
     className: clsx("coop-fieldset", className),
     "data-error": error || undefined,
     "data-hide-error": hideErrorBar || undefined,
     disabled,
+    id,
     ...props,
   }
 
   return (
-    <fieldset {...componentProps} ref={ref}>
-      {children}
-    </fieldset>
+    <FieldsetContext.Provider value={{ error: group && error, errorId, hintId }}>
+      <fieldset {...componentProps} ref={ref}>
+        {children}
+      </fieldset>
+    </FieldsetContext.Provider>
   )
 }
 
@@ -71,8 +101,12 @@ const FieldsetFields = ({
 }
 
 const FieldsetLegend = (props: LegendProps): JSX.Element => <BaseLegend {...props} />
-const FieldsetHint = (props: HintProps): JSX.Element => <BaseHint {...props} />
-const FieldsetError = (props: ErrorProps): JSX.Element => <BaseError {...props} />
+const FieldsetHint = (props: HintProps): JSX.Element => (
+  <BaseHint id={useFieldset()?.hintId} {...props} />
+)
+const FieldsetError = (props: ErrorProps): JSX.Element => (
+  <BaseError id={useFieldset()?.errorId} {...props} />
+)
 
 Fieldset.slot = { name: "Fieldset" }
 FieldsetFields.slot = { name: "FieldsetField" }

package/src/components/Radio/Radio.tsx

@@ -2,7 +2,7 @@
 import clsx from "clsx"
 import { type InputHTMLAttributes, type JSX, Ref } from "react"
 
-import { useField } from "@/components/Field/Field.context"
+import { getDescribedBy, getFieldError, useField } from "@/components/Field/Field.context"
 import { StandardSizes } from "@/types"
 
 export interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
@@ -23,9 +23,10 @@ export interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
 }
 
 const Radio = ({
+  "aria-describedby": ariaDescribedBy,
   className,
   disabled,
-  error = false,
+  error,
   id,
   name,
   ref,
@@ -33,10 +34,12 @@ const Radio = ({
   ...props
 }: RadioProps): JSX.Element => {
   const field = useField()
+  const hasError = getFieldError(error, field)
 
   const componentProps = {
+    "aria-describedby": getDescribedBy(ariaDescribedBy, field),
+    "aria-invalid": hasError || undefined,
     className: clsx("coop-radio", className),
-    "data-error": error || undefined,
     "data-size": size ?? undefined,
     disabled,
     id: id ?? field?.id,

package/src/components/Select/Select.tsx

@@ -10,7 +10,7 @@ import type {
 
 import clsx from "clsx"
 
-import { useField } from "@/components/Field/Field.context"
+import { getDescribedBy, getFieldError, useField } from "@/components/Field/Field.context"
 import { StandardSizes } from "@/types"
 
 export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "size"> {
@@ -31,8 +31,8 @@ export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement
   fit?: boolean
   /** Specify the component id. Will be auto-generated if not set. */
   id?: string
-  /** Specify the Select name. */
-  name: string
+  /** Specify the Select name. Without a name, the value is not submitted with a form. */
+  name?: string
   /** Specify a custom React ref for this component. */
   ref?: Ref<HTMLSelectElement>
   /** Specify the component size. */
@@ -54,6 +54,7 @@ interface SelectOptionProps extends OptionHTMLAttributes<HTMLOptionElement> {
 }
 
 const Select = ({
+  "aria-describedby": ariaDescribedBy,
   children,
   className,
   disabled,
@@ -66,10 +67,12 @@ const Select = ({
   ...props
 }: SelectProps): JSX.Element => {
   const field = useField()
+  const hasError = getFieldError(error, field)
 
   const componentProps = {
+    "aria-describedby": getDescribedBy(ariaDescribedBy, field),
+    "aria-invalid": hasError || undefined,
     className: clsx("coop-select", className),
-    "data-error": error ?? undefined,
     "data-fit": fit || undefined,
     "data-size": size ?? undefined,
     disabled,

package/src/components/TextInput/TextInput.tsx

@@ -3,7 +3,7 @@ import type { InputHTMLAttributes, JSX, Ref } from "react"
 
 import clsx from "clsx"
 
-import { useField } from "@/components/Field/Field.context"
+import { getDescribedBy, getFieldError, useField } from "@/components/Field/Field.context"
 import { StandardSizes } from "@/types"
 
 export interface TextInputProps extends Omit<
@@ -23,8 +23,8 @@ export interface TextInputProps extends Omit<
   fit?: boolean
   /** Specify the component id. Will be auto-generated if not set. */
   id?: string
-  /** Specify the component name. */
-  name: string
+  /** Specify the component name. Without a name, the value is not submitted with a form. */
+  name?: string
   /** Specify placeholder text. Do not use in place of a form label. */
   placeholder?: string
   /** Specify the prefix. */
@@ -56,10 +56,10 @@ export interface TextInputProps extends Omit<
 }
 
 const TextInput = ({
-  // "aria-placeholder": ariaPlaceholder,
+  "aria-describedby": ariaDescribedBy,
   className,
   disabled,
-  error = false,
+  error,
   fit = false,
   id,
   name,
@@ -74,11 +74,12 @@ const TextInput = ({
   ...props
 }: TextInputProps): JSX.Element => {
   const field = useField()
+  const hasError = getFieldError(error, field)
 
   const componentProps = {
-    // "aria-placeholder": placeholder ?? ariaPlaceholder ?? undefined,
+    "aria-describedby": getDescribedBy(ariaDescribedBy, field),
+    "aria-invalid": hasError || undefined,
     className: clsx("coop-text-input", className),
-    "data-error": error || undefined,
     "data-fit": fit || undefined,
     "data-size": size ?? undefined,
     disabled,
@@ -98,7 +99,7 @@ const TextInput = ({
     : {}
 
   return prefix || suffix ? (
-    <div className="coop-text-input-wrapper">
+    <div className="coop-text-input-wrapper" data-field="" data-size={size}>
       {prefix && <span {...prefixProps}>{prefix}</span>}
       <input {...componentProps} ref={ref} />
       {suffix && <span {...suffixProps}>{suffix}</span>}

package/src/components/Textarea/Textarea.tsx

@@ -5,7 +5,7 @@ import type { ChangeEvent, JSX, Ref, TextareaHTMLAttributes } from "react"
 import clsx from "clsx"
 import { useState } from "react"
 
-import { useField } from "@/components/Field/Field.context"
+import { getDescribedBy, getFieldError, useField } from "@/components/Field/Field.context"
 import { useDebounce } from "@/hooks/useDebounce"
 import { StandardSizes } from "@/types"
 
@@ -41,8 +41,8 @@ export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElemen
   fit?: boolean
   /** Specify the component id. Will be auto-generated if not set. */
   id?: string
-  /** Specify the component name. */
-  name: string
+  /** Specify the component name. Without a name, the value is not submitted with a form. */
+  name?: string
   /** Specify placeholder text. Do not use in place of a form label. */
   placeholder?: string
   /** Specify a custom React ref for this component. */
@@ -57,13 +57,13 @@ export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElemen
 }
 
 const Textarea = ({
-  // "aria-placeholder": ariaPlaceholder,
+  "aria-describedby": ariaDescribedBy,
   className,
   cols = 30,
   counter = false,
   cutoff = false,
   disabled = false,
-  error = false,
+  error,
   fit = false,
   id,
   maxLength,
@@ -76,12 +76,13 @@ const Textarea = ({
   ...props
 }: TextareaProps): JSX.Element => {
   const field = useField()
+  const hasError = getFieldError(error, field)
 
   const componentProps = {
-    // "aria-placeholder": placeholder ?? ariaPlaceholder ?? undefined,
+    "aria-describedby": getDescribedBy(ariaDescribedBy, field),
+    "aria-invalid": hasError || undefined,
     className: clsx("coop-textarea", className),
     cols,
-    "data-error": error ?? undefined,
     "data-fit": fit || undefined,
     "data-size": size ?? undefined,
     disabled,

package/src/components/ValidationSummary/ValidationSummary.context.ts

@@ -0,0 +1,18 @@
+"use client"
+import { createContext, useContext } from "react"
+
+import type { FieldPosition } from "./validationsummary-utils"
+
+interface ValidationSummaryContextValue {
+  /** The order of the fields in the form, read when the form is submitted. Empty until the first submit. */
+  fieldOrder: FieldPosition[]
+  /** Gets the form the summary is associated with. Call it in event handlers, not during render. */
+  getForm: () => HTMLFormElement | null
+}
+
+export const ValidationSummaryContext = createContext<ValidationSummaryContextValue>({
+  fieldOrder: [],
+  getForm: () => null,
+})
+
+export const useValidationSummary = () => useContext(ValidationSummaryContext)

package/src/components/ValidationSummary/ValidationSummary.tsx

@@ -5,12 +5,21 @@ import type { HTMLAttributes, JSX, ReactNode, Ref, RefObject } from "react"
 
 import clsx from "clsx"
 import mergeRefs from "merge-refs"
-import React, { useCallback, useEffect, useRef, useState } from "react"
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react"
 
 import {
+  type FieldError,
+  FieldPosition,
   getFieldElement,
+  getFieldOrder,
+  getForm,
   sanitizeFieldId,
+  sortErrorsByFieldOrder,
 } from "@/components/ValidationSummary/validationsummary-utils"
+import {
+  useValidationSummary,
+  ValidationSummaryContext,
+} from "@/components/ValidationSummary/ValidationSummary.context"
 import { useSlots } from "@/hooks/useSlots"
 import { getSlotProp } from "@/utils"
 
@@ -63,15 +72,6 @@ interface ValidationSummaryPromptProps extends HTMLAttributes<HTMLDivElement> {
   children?: React.ReactNode
 }
 
-interface FieldError {
-  message?: string | number
-  ref?: {
-    focus?: () => void
-    id?: string
-  }
-  type?: string | number
-}
-
 interface ValidationSummaryErrorsProps extends HTMLAttributes<HTMLDivElement> {
   /** Specify the validation error array. Refer to the FieldError type for the shape.. */
   errors?: Record<string, FieldError>
@@ -97,16 +97,25 @@ const ValidationSummary = ({
   const slots = useSlots(componentSlots, children)
 
   const errors = Object.keys(getSlotProp<FieldError>(slots.ValidationSummaryErrors, "errors") ?? {})
-
   const hasErrors = errors && errors.length > 0
   const internalRef = useRef<HTMLDivElement>(null)
 
+  const [fieldOrder, setFieldOrder] = useState<FieldPosition[]>([])
   const onSubmit = useCallback(() => {
+    const form = getForm(formRef, internalRef)
+    if (form) setFieldOrder(getFieldOrder(form))
+
     setStamp(Date.now())
-  }, [])
+  }, [formRef])
+
+  // The form is looked up when it is needed, so it is found even before the first submit
+  const context = useMemo(
+    () => ({ fieldOrder, getForm: () => getForm(formRef, internalRef) }),
+    [fieldOrder, formRef]
+  )
 
   useEffect(() => {
-    const form = formRef?.current ?? internalRef.current?.closest("form")
+    const form = getForm(formRef, internalRef)
     form?.addEventListener("submit", onSubmit)
     if (form && hasErrors && autoScroll) {
       if (typeof form?.scrollIntoView === "function") {
@@ -134,10 +143,12 @@ const ValidationSummary = ({
       role="alert"
       tabIndex={-1}
     >
-      {slots.ValidationSummaryHeading}
-      {slots.ValidationSummaryPrompt}
-      {slots.ValidationSummaryErrors}
-      {slots.Children}
+      <ValidationSummaryContext.Provider value={context}>
+        {slots.ValidationSummaryHeading}
+        {slots.ValidationSummaryPrompt}
+        {slots.ValidationSummaryErrors}
+        {slots.Children}
+      </ValidationSummaryContext.Provider>
     </div>
   )
 }
@@ -159,14 +170,16 @@ const ValidationSummaryPrompt = ({ children }: ValidationSummaryPromptProps): JS
 }
 
 const focusable = ["INPUT", "TEXTAREA", "SELECT"]
-
+const focusOptions = { focusVisible: true, preventScroll: true }
 const ValidationSummaryErrors = ({ errors }: ValidationSummaryErrorsProps): JSX.Element | null => {
   const errorsArray = (errors && Object.entries(errors)) ?? []
+  const { fieldOrder, getForm } = useValidationSummary()
+  const sortedErrors = sortErrorsByFieldOrder(errorsArray, fieldOrder)
 
   return errorsArray.length ? (
     <div className="coop-validation-summary--errors">
       <ul>
-        {errorsArray.map(([field, error]) => {
+        {sortedErrors.map(([field, error]) => {
           const id = error.ref?.id ? sanitizeFieldId(error.ref.id) : undefined
 
           return (
@@ -175,14 +188,15 @@ const ValidationSummaryErrors = ({ errors }: ValidationSummaryErrorsProps): JSX.
                 href="#"
                 onClick={(e) => {
                   e.preventDefault()
-                  const el = getFieldElement(field, id)
-                  if (el) {
-                    // if (typeof el.scrollIntoView === "function") el.scrollIntoView()
+                  const form = getForm()
+                  const el = form && getFieldElement(form, field, id)
+                  if (el instanceof HTMLElement) {
+                    el.scrollIntoView({ block: "center" })
 
                     if (focusable.includes(el.nodeName)) {
-                      el.focus()
+                      el.focus(focusOptions)
                     } else {
-                      el.querySelector("input")?.focus()
+                      el.querySelector("input")?.focus(focusOptions)
                     }
                   }
                 }}