@instructure/ui-form-field 11.7.9-snapshot-5 → 11.7.10

package/src/FormFieldGroup/v2/index.tsx

@@ -34,7 +34,8 @@ import { Grid } from '@instructure/ui-grid/latest'
 import {
   pickProps,
   omitProps,
-  safeCloneElement
+  safeCloneElement,
+  withDeterministicId
 } from '@instructure/ui-react-utils'
 import { withStyleNew } from '@instructure/emotion'
 
@@ -46,12 +47,14 @@ import generateStyle from './styles.js'
 
 import { allowedProps } from './props.js'
 import type { FormFieldGroupProps } from './props'
+import type { FormFieldLayoutChildrenParams } from '../../FormFieldLayout/v2/props'
 
 /**
 ---
 category: components
 ---
 **/
+@withDeterministicId()
 @withStyleNew(generateStyle)
 class FormFieldGroup extends Component<FormFieldGroupProps> {
   static displayName = 'FormFieldGroup'
@@ -67,6 +70,13 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
     isGroup: true
   }
 
+  constructor(props: FormFieldGroupProps) {
+    super(props)
+    this._defaultId = props.deterministicId!()
+  }
+
+  private readonly _defaultId: string
+
   ref: Element | null = null
 
   handleRef = (el: Element | null) => {
@@ -96,9 +106,10 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
     )
   }
 
-  renderColumns() {
-    const { disabled } = this.props
-    return Children.map(this.props.children, (child, index) => {
+  renderColumns(params: FormFieldLayoutChildrenParams) {
+    const { disabled, children } = this.props
+    const fields = typeof children === 'function' ? children(params) : children
+    return Children.map(fields, (child, index) => {
       if (!child) return null
       const el = child as ReactElement<any>
       const renderedChild =
@@ -116,7 +127,7 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
     })
   }
 
-  renderChildren() {
+  renderChildren(params: FormFieldLayoutChildrenParams) {
     return (
       <Grid
         colSpacing={this.props.colSpacing}
@@ -127,17 +138,17 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
           (this.props.layout === 'columns' ? 'medium' : null)
         }
       >
-        <Grid.Row>{this.renderColumns()}</Grid.Row>
+        <Grid.Row>{this.renderColumns(params)}</Grid.Row>
       </Grid>
     )
   }
 
-  renderFields() {
+  renderFields(params: FormFieldLayoutChildrenParams) {
     const { styles } = this.props
 
     return (
       <span key="fields" css={styles?.formFieldGroup}>
-        {this.renderChildren()}
+        {this.renderChildren(params)}
       </span>
     )
   }
@@ -180,12 +191,13 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
         vAlign={props.vAlign}
         layout={props.layout === 'inline' ? 'inline' : 'stacked'}
         label={props.description}
+        id={props.id || this._defaultId}
         aria-disabled={props.disabled ? 'true' : undefined}
         aria-invalid={ariaInvalid}
         elementRef={this.handleRef}
         isGroup={isGroup}
       >
-        {this.renderFields()}
+        {(params: FormFieldLayoutChildrenParams) => this.renderFields(params)}
       </FormFieldLayout>
     )
   }

package/src/FormFieldGroup/v2/props.ts

@@ -31,8 +31,12 @@ import type {
   ComponentStyle,
   Spacing
 } from '@instructure/emotion'
-import type { FormFieldLayoutOwnProps } from '../../FormFieldLayout/v2/props'
+import type {
+  FormFieldLayoutChildren,
+  FormFieldLayoutOwnProps
+} from '../../FormFieldLayout/v2/props'
 import type { FormMessage } from '../../utils/v1/FormPropTypes'
+import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
 
 type FormFieldGroupOwnProps = {
   description: React.ReactNode
@@ -60,7 +64,11 @@ type FormFieldGroupOwnProps = {
    * Whether the field group is read-only. When true, error and success messages will be hidden.
    */
   readOnly?: boolean
-  children?: React.ReactNode
+  /**
+   * The form controls. Can be a function that receives `{ describedBy }`, so
+   * the controls can reference the group messages via `aria-describedby`.
+   */
+  children?: FormFieldLayoutChildren
   layout?: 'stacked' | 'columns' | 'inline'
   rowSpacing?: 'none' | 'small' | 'medium' | 'large'
   colSpacing?: 'none' | 'small' | 'medium' | 'large'
@@ -85,11 +93,18 @@ type AllowedPropKeys = Readonly<Array<PropKeys>>
 type FormFieldGroupProps = FormFieldGroupOwnProps &
   WithStyleProps<null, FormFieldGroupStyle> &
   OtherHTMLAttributes<FormFieldGroupOwnProps> &
+  WithDeterministicIdProps &
   // Adding other props that can be passed to FormFieldLayout,
   // excluding the ones we set manually
   Omit<
     FormFieldLayoutOwnProps,
-    'messages' | 'messagesId' | 'vAlign' | 'layout' | 'label' | 'children'
+    | 'id'
+    | 'messages'
+    | 'messagesId'
+    | 'vAlign'
+    | 'layout'
+    | 'label'
+    | 'children'
   >
 
 type FormFieldGroupStyle = ComponentStyle<'formFieldGroup'>

package/src/FormFieldLayout/v2/index.tsx

@@ -32,6 +32,27 @@ import generateStyle from './styles.js'
 import { allowedProps } from './props.js'
 import type { FormFieldLayoutProps } from './props'
 
+// Elements that handle clicks themselves, do not override it
+const INTERACTIVE_SELECTOR = [
+  'a[href]',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  'label',
+  'summary',
+  'iframe',
+  'embed',
+  'object',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]'
+].join(',')
+
+// Clicks already forwarded by a nested FormFieldLayout
+const forwardedClicks = new WeakSet<Event>()
+
 /**
 ---
 parent: FormField
@@ -42,10 +63,11 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
     const {
       inline = false,
       layout = 'stacked',
-      as = 'label',
+      as = 'div',
       labelAlign = 'end',
       vAlign,
       label,
+      id,
       messages,
       messagesId: messagesIdProp,
       labelId: labelIdProp,
@@ -107,6 +129,8 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
 
     const hasVisibleLabel = label ? hasVisibleChildren(label) : false
 
+    const describedBy = hasMessages ? messagesId : undefined
+
     const invalid = !!filteredMessages?.find(
       (m) => m.type === 'error' || m.type === 'newError'
     )
@@ -159,6 +183,31 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
       [inputContainerRef]
     )
 
+    // Clicks on the rest of the control area (icons, before/after content) need
+    // to be forwarded to the control.
+    const handleChildrenClick = (e: React.MouseEvent<HTMLElement>) => {
+      if (
+        // it's a group, no clear control to forward to
+        ElementType === 'fieldset' ||
+        e.defaultPrevented ||
+        forwardedClicks.has(e.nativeEvent)
+      ) {
+        return
+      }
+      const container = e.currentTarget
+      const interactive = (e.target as Element).closest(INTERACTIVE_SELECTOR)
+      if (interactive && container.contains(interactive)) {
+        return // do not steal clicks for e.g. DateInput's calendar icon
+      }
+      const control = id ? container.ownerDocument.getElementById(id) : null
+      if (!control || !container.contains(control)) {
+        return // no control
+      }
+      forwardedClicks.add(e.nativeEvent)
+      control.focus()
+      control.click()
+    }
+
     const renderLabel = () => {
       const labelContent = hasVisibleLabel ? (
         <>
@@ -188,9 +237,9 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
           )
         }
         return (
-          <span css={styles?.formFieldLabel} id={labelId}>
+          <label css={styles?.formFieldLabel} id={labelId} htmlFor={id}>
             {labelContent}
-          </span>
+          </label>
         )
       } else if (label) {
         if (ElementType === 'fieldset') {
@@ -200,11 +249,10 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
             </legend>
           )
         }
-        // needs to be wrapped because it needs an `id`
         return (
-          <div id={labelId} style={{ display: 'contents' }}>
+          <label id={labelId} htmlFor={id} style={{ display: 'contents' }}>
             {label}
-          </div>
+          </label>
         )
       } else return null
     }
@@ -230,8 +278,16 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
       >
         {renderLabel()}
         {isGroup && renderMessages()}
-        <span css={styles?.formFieldChildren} ref={handleInputContainerRef}>
-          {children}
+        {/* Clicks are forwarded to the control. Needed for e.g. Select's down arrow */}
+        {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions */}
+        <span
+          css={styles?.formFieldChildren}
+          ref={handleInputContainerRef}
+          onClick={handleChildrenClick}
+        >
+          {typeof children === 'function'
+            ? children({ describedBy })
+            : children}
         </span>
         {!isGroup && renderMessages()}
       </ElementType>

package/src/FormFieldLayout/v2/props.ts

@@ -35,14 +35,38 @@ import type { FormMessage } from '../../utils/v1/FormPropTypes'
 import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
 import type { NewComponentTypes } from '@instructure/ui-themes'
 
+type FormFieldLayoutChildrenParams = {
+  /**
+   * The id of the rendered messages, or `undefined` when no messages are
+   * shown. Add it to the control's `aria-describedby`.
+   */
+  describedBy?: string
+}
+
+type FormFieldLayoutChildren =
+  | React.ReactNode
+  | ((params: FormFieldLayoutChildrenParams) => React.ReactNode)
+
 type FormFieldLayoutOwnProps = {
+  /**
+   * The label text. Will be appended by a `*` if this field is required.
+   */
   label: React.ReactNode
   /**
-   * the id of the input (to link it to its label for a11y)
+   * The id of the form control (=the child of this component). It's applied as the
+   * [for](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/for)
+   * attribute of the label, so the control needs to have the same `id`.
+   * Not used when rendering as a `fieldset` (group)
    */
-  id?: string
+  id: string
   /**
-   * the element type to render as
+   * The element type to render as, `div` be default.
+   *
+   * Also determines how the `label` will be rendered:
+   * If its value is `fieldset` (for form groups), it be rendered in a
+   * [legend](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/legend),
+   * for all other cases it will be in a
+   * [label](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label).
    */
   as?: AsElementType
   /**
@@ -57,11 +81,18 @@ type FormFieldLayoutOwnProps = {
    */
   messagesId?: string
   /**
-   * id for the label element, so a single form control can reference just the
-   * label text via `aria-labelledby` (keeping messages out of its accessible name)
+   * `id` for the label/legend element. Useful when the control is not a
+   * [labelable](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Content_categories#labelable)
+   * element (e.g. a custom widget), and needs to reference the label via
+   * `aria-labelledby={labelId}`.
    */
   labelId?: string
-  children?: React.ReactNode
+  /**
+   * The form control(s). Can be a function that receives
+   * `{ describedBy }`, so the control can reference the messages via
+   * `aria-describedby`.
+   */
+  children?: FormFieldLayoutChildren
   /**
    * If `true` use an inline layout -- content will flow on the left/right side
    * of this component
@@ -157,6 +188,8 @@ type FormFieldStyleProps = {
 }
 
 export type {
+  FormFieldLayoutChildren,
+  FormFieldLayoutChildrenParams,
   FormFieldStyleProps,
   FormFieldLayoutProps,
   FormFieldLayoutStyle,

package/src/FormFieldLayout/v2/styles.ts

@@ -121,6 +121,7 @@ const generateStyle = (
     fontWeight: componentTheme.fontWeight,
     fontSize: componentTheme.fontSize,
     lineHeight: componentTheme.lineHeight,
+    paddingBottom: hasVisibleMessage ? '0' : componentTheme.gapPrimitives,
     ...(isInlineLayout && {
       margin: '0',
       // when inline add a small padding between the label and the control
@@ -179,8 +180,7 @@ const generateStyle = (
       ...labelStyles,
       // NOTE: needs separate groups for `:is()` and `:-webkit-any()` because of css selector group validation (see https://www.w3.org/TR/selectors-3/#grouping)
       '&:is(label)': labelStyles,
-      '&:-webkit-any(label)': labelStyles,
-      paddingBottom: hasVisibleMessage ? '0' : componentTheme.gapPrimitives
+      '&:-webkit-any(label)': labelStyles
     },
     formFieldChildren: {
       label: 'formFieldLayout__children',

package/src/exports/b.ts

@@ -36,5 +36,8 @@ export type {
 export type { FormFieldOwnProps, FormFieldProps } from '../FormField/v2/props'
 export type { FormFieldMessageProps } from '../FormFieldMessage/v2/props'
 export type { FormFieldMessagesProps } from '../FormFieldMessages/v2/props'
-export type { FormFieldLayoutProps } from '../FormFieldLayout/v2/props'
+export type {
+  FormFieldLayoutProps,
+  FormFieldLayoutChildrenParams
+} from '../FormFieldLayout/v2/props'
 export type { FormFieldGroupProps } from '../FormFieldGroup/v2/props'