@instructure/ui-form-field 9.10.2 → 9.11.1

package/lib/FormFieldMessages/styles.js

@@ -35,16 +35,18 @@ exports.default = void 0;
  * Generates the style object from the theme and provided additional information
  * @param  {Object} componentTheme The theme variable object.
  * @param  {Object} props the props of the component, the style is applied to
- * @param  {Object} state the state of the component, the style is applied to
  * @return {Object} The final style object, which will be used in the component
  */
-const generateStyle = componentTheme => {
+const generateStyle = (componentTheme, props) => {
   return {
     formFieldMessages: {
       label: 'formFieldMessages',
       padding: 0,
       display: 'block',
-      margin: `calc(-1 * ${componentTheme.topMargin}) 0 0 0`
+      margin: `calc(-${componentTheme.topMargin}) 0 0 0`,
+      ...(props.gridArea && {
+        gridArea: props.gridArea
+      })
     },
     message: {
       label: 'formFieldMessages__message',

package/lib/FormPropTypes.js

@@ -32,6 +32,12 @@ var _propTypes = _interopRequireDefault(require("prop-types"));
 
 const formMessageTypePropType = exports.formMessageTypePropType = _propTypes.default.oneOf(['error', 'newError', 'hint', 'success', 'screenreader-only']);
 const formMessageChildPropType = exports.formMessageChildPropType = _propTypes.default.node;
+
+// TODO it will be easier if this would be just a string
+/**
+ * The text to display in the form message
+ */
+
 /**
  * ---
  * category: utilities/form

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-form-field",
-  "version": "9.10.2",
+  "version": "9.11.1",
   "description": "Form layout components.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -23,26 +23,26 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@instructure/ui-axe-check": "9.10.2",
-    "@instructure/ui-babel-preset": "9.10.2",
-    "@instructure/ui-test-utils": "9.10.2",
-    "@instructure/ui-themes": "9.10.2",
+    "@instructure/ui-axe-check": "9.11.1",
+    "@instructure/ui-babel-preset": "9.11.1",
+    "@instructure/ui-test-utils": "9.11.1",
+    "@instructure/ui-themes": "9.11.1",
     "@testing-library/jest-dom": "^6.4.6",
     "@testing-library/react": "^15.0.7",
     "vitest": "^2.0.2"
   },
   "dependencies": {
     "@babel/runtime": "^7.24.5",
-    "@instructure/console": "9.10.2",
-    "@instructure/emotion": "9.10.2",
-    "@instructure/shared-types": "9.10.2",
-    "@instructure/ui-a11y-content": "9.10.2",
-    "@instructure/ui-a11y-utils": "9.10.2",
-    "@instructure/ui-grid": "9.10.2",
-    "@instructure/ui-icons": "9.10.2",
-    "@instructure/ui-react-utils": "9.10.2",
-    "@instructure/ui-utils": "9.10.2",
-    "@instructure/uid": "9.10.2",
+    "@instructure/console": "9.11.1",
+    "@instructure/emotion": "9.11.1",
+    "@instructure/shared-types": "9.11.1",
+    "@instructure/ui-a11y-content": "9.11.1",
+    "@instructure/ui-a11y-utils": "9.11.1",
+    "@instructure/ui-grid": "9.11.1",
+    "@instructure/ui-icons": "9.11.1",
+    "@instructure/ui-react-utils": "9.11.1",
+    "@instructure/ui-utils": "9.11.1",
+    "@instructure/uid": "9.11.1",
     "prop-types": "^15.8.1"
   },
   "peerDependencies": {

package/src/FormField/README.md

@@ -9,7 +9,35 @@ components. In most cases it shouldn't be used directly.
 ---
 type: example
 ---
-<FormField id="foo" label="Opacity" width="200px">
-  <input style={{display: 'block', width: '100%'}}/>
-</FormField>
+<div>
+  <FormField id="_foo121" label="Stacked layout" width="400px" layout="stacked"
+             messages={[{type:'success', text: 'This is a success message'}, {type:'newError', text: 'An error message. It will wrap if the text is longer than the width of the container.'}]}>
+    <TextInput id="_foo121"/>
+  </FormField>
+  test
+  <hr/>
+  <FormField id="_foo122" label="Stacked layout (inline=true)" width="400px" layout="stacked" inline
+             messages={[{type:'success', text: 'This is a success message'}, {type:'newError', text: 'An error message. It will wrap if the text is longer than the width of the container.'}]}>
+    <TextInput id="_foo122"/>
+  </FormField>
+  test
+  <hr/>
+  <FormField id="_foo123" label="Inline layout" width="400px" layout="inline"
+             messages={[{type:'success', text: 'success!'}, {type:'newError', text: 'An error message. It will wrap if the text is longer than the width of the container.'}]}>
+    <TextInput id="_foo123"/>
+  </FormField>
+  test
+  <hr/>
+  <FormField id="_foo124" label="Inline layout (inline=true)" width="400px" layout="inline" inline
+             messages={[{type:'success', text: 'success!'}, {type:'newError', text: 'An error message. It will wrap if the text is longer than the width of the container.'}]}>
+    <TextInput id="_foo124"/>
+  </FormField>
+  test
+  <hr/>
+  <FormField id="_foo121" label={<ScreenReaderContent>hidden text</ScreenReaderContent>} width="400px" layout="stacked">
+    <TextInput id="_foo121" />
+  </FormField>
+  test
+  <hr/>
+</div>
 ```

package/src/FormField/index.tsx

@@ -68,6 +68,9 @@ class FormField extends Component<FormFieldProps> {
         label={this.props.label}
         vAlign={this.props.vAlign}
         as="label"
+        // This makes the control in focus when the label is clicked
+        // This is needed to prevent the wrong element to be focused, e.g.
+        // multi selects Tag-s
         htmlFor={this.props.id}
         elementRef={this.handleRef}
       />

package/src/FormFieldGroup/__new-tests__/FormFieldGroup.test.tsx

@@ -66,7 +66,7 @@ describe('<FormFieldGroup />', () => {
     )
 
     const formFieldGroup = container.querySelector(
-      "fieldset[class$='-formFieldLayout']"
+      "span[class$='-formFieldLayout__label']"
     )
     const firstNameInput = screen.getByLabelText('First:')
     const middleNameInput = screen.getByLabelText('Middle:')
@@ -94,9 +94,7 @@ describe('<FormFieldGroup />', () => {
       </FormFieldGroup>
     )
 
-    const formFieldGroup = container.querySelector(
-      "fieldset[class$='-formFieldLayout']"
-    )
+    const formFieldGroup = container.querySelector('label')
 
     expect(formFieldGroup).toBeInTheDocument()
   })
@@ -136,7 +134,7 @@ describe('<FormFieldGroup />', () => {
     expect(message).toHaveAttribute('id', messagesId)
   })
 
-  it('displays description message inside the legend', () => {
+  it('displays description message inside the label', () => {
     const description = 'Please enter your full name'
 
     const { container } = render(
@@ -154,7 +152,7 @@ describe('<FormFieldGroup />', () => {
     )
 
     const legend = container.querySelector(
-      "legend[class$='-screenReaderContent']"
+      "span[class$='-formFieldLayout__label']"
     )
 
     expect(legend).toBeInTheDocument()

package/src/FormFieldGroup/index.tsx

@@ -23,7 +23,7 @@
  */
 
 /** @jsx jsx */
-import { Component, Children, ReactElement } from 'react'
+import { Component, Children, ReactElement, AriaAttributes } from 'react'
 
 import { Grid } from '@instructure/ui-grid'
 import { pickProps, omitProps } from '@instructure/ui-react-utils'
@@ -53,7 +53,8 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
     disabled: false,
     rowSpacing: 'medium',
     colSpacing: 'small',
-    vAlign: 'middle'
+    vAlign: 'middle',
+    isGroup: true
   }
 
   ref: Element | null = null
@@ -77,14 +78,20 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
   }
 
   get makeStylesVariables(): FormFieldGroupStyleProps {
-    return { invalid: this.invalid }
+    // new form errors dont need borders
+    const oldInvalid =
+      !!this.props.messages &&
+      this.props.messages.findIndex((message) => {
+        return message.type === 'error'
+      }) >= 0
+    return { invalid: oldInvalid }
   }
 
   get invalid() {
     return (
       !!this.props.messages &&
       this.props.messages.findIndex((message) => {
-        return message.type === 'error'
+        return message.type === 'error' || message.type === 'newError'
       }) >= 0
     )
   }
@@ -134,7 +141,35 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
 
   render() {
     const { styles, makeStyles, isGroup, ...props } = this.props
-
+    // This is quite ugly, but according to ARIA spec the `aria-invalid` prop
+    // can only be used with certain roles see
+    // https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid#associated_roles
+    // `aria-invalid` is put on in FormFieldLayout because the error message
+    // DOM part gets there its ID.
+    let ariaInvalid: AriaAttributes['aria-invalid'] = undefined
+    if (
+      this.props.role &&
+      this.invalid &&
+      [
+        'application',
+        'checkbox',
+        'combobox',
+        'gridcell',
+        'listbox',
+        'radiogroup',
+        'slider',
+        'spinbutton',
+        'textbox',
+        'tree',
+        'columnheader',
+        'rowheader',
+        'searchbox',
+        'switch',
+        'treegrid'
+      ].includes(this.props.role)
+    ) {
+      ariaInvalid = 'true'
+    }
     return (
       <FormFieldLayout
         {...omitProps(props, FormFieldGroup.allowedProps)}
@@ -143,7 +178,7 @@ class FormFieldGroup extends Component<FormFieldGroupProps> {
         layout={props.layout === 'inline' ? 'inline' : 'stacked'}
         label={props.description}
         aria-disabled={props.disabled ? 'true' : undefined}
-        aria-invalid={this.invalid ? 'true' : undefined}
+        aria-invalid={ariaInvalid}
         elementRef={this.handleRef}
         isGroup={isGroup}
       >

package/src/FormFieldLabel/index.tsx

@@ -25,7 +25,11 @@
 /** @jsx jsx */
 import { Component } from 'react'
 
-import { omitProps, getElementType } from '@instructure/ui-react-utils'
+import {
+  omitProps,
+  getElementType,
+  deprecated
+} from '@instructure/ui-react-utils'
 import { withStyle, jsx } from '@instructure/emotion'
 
 import generateStyle from './styles'
@@ -39,8 +43,7 @@ import type { FormFieldLabelProps } from './props'
 parent: FormField
 ---
 
-This is a helper component that is used by most of the custom form
-components. In most cases it shouldn't be used directly.
+This is a helper component that is used by most of the custom form components. In most cases it shouldn't be used directly.
 
 ```js
 ---
@@ -49,8 +52,10 @@ type: example
 <FormFieldLabel>Hello</FormFieldLabel>
 ```
 
+@deprecated This is an internal component that will be removed in the future
 **/
 @withStyle(generateStyle, generateComponentTheme)
+@deprecated('10', null, 'This component will be removed in a future version')
 class FormFieldLabel extends Component<FormFieldLabelProps> {
   static readonly componentId = 'FormFieldLabel'
 

package/src/FormFieldLayout/__new-tests__/FormFieldLayout.test.tsx

@@ -23,7 +23,7 @@
  */
 
 import React from 'react'
-import { render, screen } from '@testing-library/react'
+import { render } from '@testing-library/react'
 import { vi } from 'vitest'
 import { runAxeCheck } from '@instructure/ui-axe-check'
 import '@testing-library/jest-dom'
@@ -56,7 +56,7 @@ describe('<FormFieldLayout />', () => {
       "label[class$='-formFieldLayout']"
     )
     const formFieldLabel = container.querySelector(
-      "span[class$='-formFieldLabel']"
+      "span[class$='-formFieldLayout__label']"
     )
 
     expect(formFieldLayout).toBeInTheDocument()
@@ -74,15 +74,13 @@ describe('<FormFieldLayout />', () => {
 
   it('should provide a ref to the input container', () => {
     const inputContainerRef = vi.fn()
-
+    const ref = React.createRef<HTMLInputElement>()
     render(
       <FormFieldLayout label="Username" inputContainerRef={inputContainerRef}>
-        <input type="text" />
+        <input type="text" ref={ref} />
       </FormFieldLayout>
     )
-
-    const input = screen.getByLabelText('Username')
-
-    expect(inputContainerRef).toHaveBeenCalledWith(input.parentElement)
+    expect(ref.current).toBeInstanceOf(HTMLInputElement)
+    expect(inputContainerRef).toHaveBeenCalledWith(ref.current!.parentElement)
   })
 })

package/src/FormFieldLayout/index.tsx

@@ -24,27 +24,19 @@
 
 /** @jsx jsx */
 import { Component } from 'react'
-
 import { hasVisibleChildren } from '@instructure/ui-a11y-utils'
-import { ScreenReaderContent } from '@instructure/ui-a11y-content'
-import { Grid } from '@instructure/ui-grid'
-import { logError as error } from '@instructure/console'
 import {
   omitProps,
-  pickProps,
   getElementType,
   withDeterministicId
 } from '@instructure/ui-react-utils'
 
 import { withStyle, jsx } from '@instructure/emotion'
-
-import { FormFieldLabel } from '../FormFieldLabel'
 import { FormFieldMessages } from '../FormFieldMessages'
-
 import generateStyle from './styles'
-
-import { propTypes, allowedProps } from './props'
+import { propTypes, allowedProps, FormFieldStyleProps } from './props'
 import type { FormFieldLayoutProps } from './props'
+import generateComponentTheme from './theme'
 
 /**
 ---
@@ -52,7 +44,7 @@ parent: FormField
 ---
 **/
 @withDeterministicId()
-@withStyle(generateStyle, null)
+@withStyle(generateStyle, generateComponentTheme)
 class FormFieldLayout extends Component<FormFieldLayoutProps> {
   static readonly componentId = 'FormFieldLayout'
 
@@ -67,19 +59,12 @@ class FormFieldLayout extends Component<FormFieldLayoutProps> {
 
   constructor(props: FormFieldLayoutProps) {
     super(props)
-
     this._messagesId = props.messagesId || props.deterministicId!()
-
-    error(
-      typeof props.width !== 'undefined' ||
-        !props.inline ||
-        props.layout !== 'inline',
-      `[FormFieldLayout] The 'inline' prop is true, and the 'layout' is set to 'inline'.
-      This will cause a layout issue in Internet Explorer 11 unless you also add a value for the 'width' prop.`
-    )
+    this._labelId = props.deterministicId!('FormField-Label')
   }
 
   private _messagesId: string
+  private _labelId: string
 
   ref: Element | null = null
 
@@ -94,31 +79,51 @@ class FormFieldLayout extends Component<FormFieldLayoutProps> {
   }
 
   componentDidMount() {
-    this.props.makeStyles?.()
+    this.props.makeStyles?.(this.makeStyleProps())
   }
 
   componentDidUpdate() {
-    this.props.makeStyles?.()
+    this.props.makeStyles?.(this.makeStyleProps())
+  }
+
+  makeStyleProps = (): FormFieldStyleProps => {
+    const hasNewErrorMsgAndIsGroup =
+      !!this.props.messages?.find((m) => m.type === 'newError') &&
+      !!this.props.isGroup
+    return {
+      hasMessages: this.hasMessages,
+      hasVisibleLabel: this.hasVisibleLabel,
+      // if true render error message above the controls (and below the label)
+      hasNewErrorMsgAndIsGroup: hasNewErrorMsgAndIsGroup
+    }
   }
 
   get hasVisibleLabel() {
-    return this.props.label && hasVisibleChildren(this.props.label)
+    return this.props.label ? hasVisibleChildren(this.props.label) : false
   }
 
   get hasMessages() {
-    return this.props.messages && this.props.messages.length > 0
+    if (!this.props.messages || this.props.messages.length == 0) {
+      return false
+    }
+    for (const msg of this.props.messages) {
+      if (msg.text) {
+        if (typeof msg.text === 'string') {
+          return msg.text.length > 0
+        }
+        // this is more complicated (e.g. an array, a React component,...)
+        // but we don't try to optimize here for these cases
+        return true
+      }
+    }
+    return false
   }
 
   get elementType() {
     return getElementType(FormFieldLayout, this.props)
   }
 
-  get inlineContainerAndLabel() {
-    // Return if both the component container and label will display inline
-    return this.props.inline && this.props.layout === 'inline'
-  }
-
-  handleInputContainerRef = (node: HTMLSpanElement | null) => {
+  handleInputContainerRef = (node: HTMLElement | null) => {
     if (typeof this.props.inputContainerRef === 'function') {
       this.props.inputContainerRef(node)
     }
@@ -126,99 +131,77 @@ class FormFieldLayout extends Component<FormFieldLayoutProps> {
 
   renderLabel() {
     if (this.hasVisibleLabel) {
+      if (this.elementType == 'fieldset') {
+        // `legend` has some special built in CSS, this can only be reset
+        // this way https://stackoverflow.com/a/65866981/319473
+        return (
+          <legend style={{ display: 'contents' }}>
+            <span css={this.props.styles?.formFieldLabel}>
+              {this.props.label}
+            </span>
+          </legend>
+        )
+      }
       return (
-        <Grid.Col
-          textAlign={this.props.labelAlign}
-          width={this.inlineContainerAndLabel ? 'auto' : 3}
-        >
-          <FormFieldLabel
-            aria-hidden={this.elementType === 'fieldset' ? 'true' : undefined}
-          >
+        <span css={this.props.styles?.formFieldLabel}>{this.props.label}</span>
+      )
+    } else if (this.props.label) {
+      if (this.elementType == 'fieldset') {
+        return (
+          <legend id={this._labelId} style={{ display: 'contents' }}>
             {this.props.label}
-          </FormFieldLabel>
-        </Grid.Col>
+          </legend>
+        )
+      }
+      // needs to be wrapped because it needs an `id`
+      return (
+        <div id={this._labelId} style={{ display: 'contents' }}>
+          {this.props.label}
+        </div>
       )
-    } else if (this.elementType !== 'fieldset') {
-      // to avoid duplicate label/legend content
-      return this.props.label
-    } else {
-      return null
-    }
-  }
-
-  renderLegend() {
-    // note: the legend element must be the first child of a fieldset element for SR
-    // so we render it twice in that case (once for SR-only and one that is visible)
-    return (
-      <ScreenReaderContent as="legend">
-        {this.props.label}
-        {this.hasMessages && (
-          <FormFieldMessages messages={this.props.messages} />
-        )}
-      </ScreenReaderContent>
-    )
+    } else return null
   }
 
   renderVisibleMessages() {
     return this.hasMessages ? (
-      <Grid.Row>
-        <Grid.Col
-          offset={this.inlineContainerAndLabel ? undefined : 3}
-          textAlign={this.inlineContainerAndLabel ? 'end' : undefined}
-        >
-          <FormFieldMessages
-            id={this._messagesId}
-            messages={this.props.messages}
-          />
-        </Grid.Col>
-      </Grid.Row>
+      <FormFieldMessages
+        id={this._messagesId}
+        messages={this.props.messages}
+        gridArea="messages"
+      />
     ) : null
   }
 
   render() {
-    // any cast is needed to prevent Expression produces a union type that is too complex to represent errors
-    const ElementType = this.elementType as any
+    // Should be `<label>` if it's a FormField, fieldset if it's a group
+    const ElementType = this.elementType
 
     const { makeStyles, styles, messages, isGroup, ...props } = this.props
 
-    const { width, layout, children } = props
+    const { width, children } = props
 
-    const hasNewErrorMsg =
+    const hasNewErrorMsgAndIsGroup =
       !!messages?.find((m) => m.type === 'newError') && isGroup
     return (
       <ElementType
-        {...omitProps(props, [
-          ...FormFieldLayout.allowedProps,
-          ...Grid.allowedProps
-        ])}
+        {...omitProps(props, [...FormFieldLayout.allowedProps])}
         css={styles?.formFieldLayout}
-        style={{ width }}
         aria-describedby={this.hasMessages ? this._messagesId : undefined}
+        aria-errormessage={
+          this.props['aria-invalid'] ? this._messagesId : undefined
+        }
+        style={{ width }}
         ref={this.handleRef}
       >
-        {this.elementType === 'fieldset' && this.renderLegend()}
-        <Grid
-          rowSpacing="small"
-          colSpacing="small"
-          startAt={
-            layout === 'inline' && this.hasVisibleLabel ? 'medium' : null
-          }
-          {...pickProps(props, Grid.allowedProps)}
+        {this.renderLabel()}
+        {hasNewErrorMsgAndIsGroup && this.renderVisibleMessages()}
+        <span
+          css={styles?.formFieldChildren}
+          ref={this.handleInputContainerRef}
         >
-          <Grid.Row>
-            {this.renderLabel()}
-            <Grid.Col
-              width={this.inlineContainerAndLabel ? 'auto' : undefined}
-              elementRef={this.handleInputContainerRef}
-            >
-              {hasNewErrorMsg && (
-                <div css={styles?.groupErrorMessage}>{this.renderVisibleMessages()}</div>
-              )}
-              {children}
-            </Grid.Col>
-          </Grid.Row>
-          {!hasNewErrorMsg && this.renderVisibleMessages()}
-        </Grid>
+          {children}
+        </span>
+        {!hasNewErrorMsgAndIsGroup && this.renderVisibleMessages()}
       </ElementType>
     )
   }

package/src/FormFieldLayout/props.ts

@@ -57,12 +57,31 @@ type FormFieldLayoutOwnProps = {
    */
   messagesId?: string
   children?: React.ReactNode
+  /**
+   * If `true` use an inline layout -- content will flow on the left/right side
+   * of this component
+   */
   inline?: boolean
+  /**
+   * In `stacked` mode the container is below the label, in `inline` mode the
+   * container is to the right/left (depending on text direction)
+   */
   layout?: 'stacked' | 'inline'
+  /**
+   * The horizontal alignment of the label. Only works in `inline` layout
+   */
   labelAlign?: 'start' | 'end'
+  /**
+   * The vertical alignment of the label and the controls.
+   * "top" by default
+   */
   vAlign?: 'top' | 'middle' | 'bottom'
   width?: string
-  inputContainerRef?: (element: HTMLSpanElement | null) => void
+  /**
+   * Provides a reference to the container that holds the input element
+   * @param element The element that holds the input control as its children
+   */
+  inputContainerRef?: (element: HTMLElement | null) => void
   /**
    * provides a reference to the underlying html root element
    */
@@ -80,7 +99,7 @@ type FormFieldLayoutProps = FormFieldLayoutOwnProps &
   WithDeterministicIdProps
 
 type FormFieldLayoutStyle = ComponentStyle<
-  'formFieldLayout' | 'groupErrorMessage'
+  'formFieldLayout' | 'formFieldLabel' | 'formFieldChildren'
 >
 
 const propTypes: PropValidators<PropKeys> = {
@@ -112,14 +131,18 @@ const allowedProps: AllowedPropKeys = [
   'labelAlign',
   'width',
   'inputContainerRef',
-  'elementRef'
-
-  // added vAlign because FormField and FormFieldGroup passes it, but not adding
-  // it to allowedProps to prevent it from getting passed through accidentally
-  //'vAlign'
+  'elementRef',
+  'vAlign'
 ]
 
+type FormFieldStyleProps = {
+  hasMessages: boolean
+  hasVisibleLabel: boolean
+  hasNewErrorMsgAndIsGroup: boolean
+}
+
 export type {
+  FormFieldStyleProps,
   FormFieldLayoutProps,
   FormFieldLayoutStyle,
   FormFieldLayoutOwnProps