@instructure/ui-form-field 11.6.0 → 11.6.1-snapshot-129

package/src/FormFieldLayout/v2/index.tsx

@@ -0,0 +1,237 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { forwardRef, useEffect, useState, useCallback } from 'react'
+import { hasVisibleChildren } from '@instructure/ui-a11y-utils'
+import { omitProps, useDeterministicId } from '@instructure/ui-react-utils'
+
+import { useStyle } from '@instructure/emotion'
+import { FormFieldMessages } from '../../FormFieldMessages/v2'
+import generateStyle from './styles'
+import { allowedProps } from './props'
+import type { FormFieldLayoutProps } from './props'
+
+/**
+---
+parent: FormField
+---
+**/
+const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
+  (props, ref) => {
+    const {
+      inline = false,
+      layout = 'stacked',
+      as = 'label',
+      labelAlign = 'end',
+      vAlign,
+      label,
+      messages,
+      messagesId: messagesIdProp,
+      children,
+      width,
+      elementRef,
+      inputContainerRef,
+      isGroup,
+      isRequired = false,
+      margin,
+      disabled = false,
+      readOnly = false,
+      themeOverride,
+      ...rest
+    } = props
+
+    // Deterministic ID generation
+    const [deterministicId, setDeterministicId] = useState<string | undefined>()
+    const getId = useDeterministicId('FormFieldLayout')
+    useEffect(() => {
+      setDeterministicId(getId())
+    }, [])
+
+    const messagesId = messagesIdProp || deterministicId
+    const labelId = deterministicId ? `${deterministicId}-Label` : undefined
+
+    // Filter out error and success messages when disabled or readOnly
+    const filteredMessages =
+      disabled || readOnly
+        ? messages?.filter(
+            (msg) =>
+              msg.type !== 'error' &&
+              msg.type !== 'newError' &&
+              msg.type !== 'success'
+          )
+        : messages
+
+    // Compute style props
+    const hasMessages =
+      filteredMessages && filteredMessages.length > 0
+        ? filteredMessages.some((msg) => {
+            if (msg.text) {
+              if (typeof msg.text === 'string') {
+                return msg.text.length > 0
+              }
+              return true
+            }
+            return false
+          })
+        : false
+
+    const hasVisibleLabel = label ? hasVisibleChildren(label) : false
+
+    const hasErrorMsgAndIsGroup =
+      !!filteredMessages?.find(
+        (m) => m.type === 'error' || m.type === 'newError'
+      ) && !!isGroup
+
+    const invalid = !!filteredMessages?.find(
+      (m) => m.type === 'error' || m.type === 'newError'
+    )
+
+    // Styles
+    const styles = useStyle({
+      generateStyle,
+      themeOverride,
+      params: {
+        hasMessages,
+        hasVisibleLabel,
+        hasErrorMsgAndIsGroup,
+        inline,
+        layout,
+        vAlign,
+        labelAlign,
+        margin,
+        messages: filteredMessages,
+        isRequired,
+        invalid
+      },
+      componentId: 'FormFieldLayout',
+      displayName: 'FormFieldLayout'
+    })
+
+    const ElementType = as
+
+    const handleRef = useCallback(
+      (el: Element | null) => {
+        if (typeof ref === 'function') {
+          ref(el)
+        } else if (ref) {
+          const refObject = ref as React.MutableRefObject<Element | null>
+          refObject.current = el
+        }
+
+        if (typeof elementRef === 'function') {
+          elementRef(el)
+        }
+      },
+      [ref, elementRef]
+    )
+
+    const handleInputContainerRef = useCallback(
+      (node: HTMLElement | null) => {
+        if (typeof inputContainerRef === 'function') {
+          inputContainerRef(node)
+        }
+      },
+      [inputContainerRef]
+    )
+
+    const renderLabel = () => {
+      const labelContent = hasVisibleLabel ? (
+        <>
+          {label}
+          {isRequired && (
+            <span
+              css={invalid ? styles?.requiredAsterisk : {}}
+              aria-hidden={true}
+            >
+              {' '}
+              *
+            </span>
+          )}
+        </>
+      ) : (
+        label
+      )
+
+      if (hasVisibleLabel) {
+        if (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={styles?.formFieldLabel}>{labelContent}</span>
+            </legend>
+          )
+        }
+        return <span css={styles?.formFieldLabel}>{labelContent}</span>
+      } else if (label) {
+        if (ElementType === 'fieldset') {
+          return (
+            <legend id={labelId} style={{ display: 'contents' }}>
+              {label}
+            </legend>
+          )
+        }
+        // needs to be wrapped because it needs an `id`
+        return (
+          <div id={labelId} style={{ display: 'contents' }}>
+            {label}
+          </div>
+        )
+      } else return null
+    }
+
+    const renderVisibleMessages = () => {
+      return hasMessages ? (
+        <FormFieldMessages
+          id={messagesId}
+          messages={filteredMessages}
+          gridArea="messages"
+        />
+      ) : null
+    }
+
+    return (
+      <ElementType
+        {...omitProps(rest, [...allowedProps])}
+        css={styles?.formFieldLayout}
+        aria-describedby={hasMessages ? messagesId : undefined}
+        aria-errormessage={rest['aria-invalid'] ? messagesId : undefined}
+        style={{ width }}
+        ref={handleRef}
+      >
+        {renderLabel()}
+        {hasErrorMsgAndIsGroup && renderVisibleMessages()}
+        <span css={styles?.formFieldChildren} ref={handleInputContainerRef}>
+          {children}
+        </span>
+        {!hasErrorMsgAndIsGroup && renderVisibleMessages()}
+      </ElementType>
+    )
+  }
+)
+
+FormFieldLayout.displayName = 'FormFieldLayout'
+
+export default FormFieldLayout
+export { FormFieldLayout, allowedProps }

package/src/FormFieldLayout/v2/props.ts

@@ -0,0 +1,157 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type {
+  AsElementType,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type {
+  ComponentStyle,
+  Spacing,
+  ThemeOverrideValue
+} from '@instructure/emotion'
+import type { FormMessage } from '../../utils/v1/FormPropTypes'
+import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
+
+type FormFieldLayoutOwnProps = {
+  label: React.ReactNode
+  /**
+   * the id of the input (to link it to its label for a11y)
+   */
+  id?: string
+  /**
+   * the element type to render as
+   */
+  as?: AsElementType
+  /**
+   * Array of objects with shape: `{
+   *   text: React.ReactNode,
+   *   type: One of: ['newError', 'error', 'hint', 'success', 'screenreader-only']
+   * }`
+   */
+  messages?: FormMessage[]
+  /**
+   * id for the form field messages
+   */
+  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
+  /**
+   * 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
+   */
+  elementRef?: (element: Element | null) => void
+  isGroup?: boolean
+  /**
+   * If `true`, displays an asterisk after the label to indicate the field is required
+   */
+  isRequired?: boolean
+
+  /**
+   * Valid values are `0`, `none`, `auto`, and Spacing token values,
+   * see https://instructure.design/layout-spacing. Apply these values via
+   * familiar CSS-like shorthand. For example, `margin="small auto large"`.
+   */
+  margin?: Spacing
+  /**
+   * Whether the field is disabled. When true, error and success messages will be hidden.
+   */
+  disabled?: boolean
+  /**
+   * Whether the field is read-only. When true, error and success messages will be hidden.
+   */
+  readOnly?: boolean
+}
+
+type PropKeys = keyof FormFieldLayoutOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type FormFieldLayoutProps = FormFieldLayoutOwnProps & {
+  themeOverride?: ThemeOverrideValue
+} & OtherHTMLAttributes<FormFieldLayoutOwnProps> &
+  WithDeterministicIdProps
+
+type FormFieldLayoutStyle = ComponentStyle<
+  | 'formFieldLayout'
+  | 'formFieldLabel'
+  | 'formFieldChildren'
+  | 'requiredAsterisk'
+>
+const allowedProps: AllowedPropKeys = [
+  'label',
+  'id',
+  'as',
+  'messages',
+  'messagesId',
+  'children',
+  'inline',
+  'layout',
+  'labelAlign',
+  'width',
+  'inputContainerRef',
+  'elementRef',
+  'margin',
+  'vAlign',
+  'isRequired',
+  'disabled',
+  'readOnly'
+]
+
+type FormFieldStyleProps = {
+  hasMessages: boolean
+  hasVisibleLabel: boolean
+  hasErrorMsgAndIsGroup: boolean
+}
+
+export type {
+  FormFieldStyleProps,
+  FormFieldLayoutProps,
+  FormFieldLayoutStyle,
+  FormFieldLayoutOwnProps
+}
+export { allowedProps }

package/src/FormFieldLayout/v2/styles.ts

@@ -0,0 +1,209 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type {
+  FormFieldLayoutProps,
+  FormFieldLayoutStyle,
+  FormFieldStyleProps
+} from './props'
+import type { NewComponentTypes, SharedTokens } from '@instructure/ui-themes'
+import { calcSpacingFromShorthand } from '@instructure/emotion'
+
+type StyleParams = FormFieldStyleProps & {
+  inline: FormFieldLayoutProps['inline']
+  layout: FormFieldLayoutProps['layout']
+  vAlign: FormFieldLayoutProps['vAlign']
+  labelAlign: FormFieldLayoutProps['labelAlign']
+  margin: FormFieldLayoutProps['margin']
+  messages: FormFieldLayoutProps['messages']
+  isRequired: FormFieldLayoutProps['isRequired']
+  invalid: boolean
+}
+
+const generateGridLayout = (
+  isInlineLayout: boolean,
+  hasErrorMsgAndIsGroup: boolean,
+  hasVisibleLabel: boolean,
+  hasMessages: boolean
+) => {
+  if (isInlineLayout) {
+    if (hasErrorMsgAndIsGroup) {
+      if (hasMessages) {
+        return `${hasVisibleLabel ? ' "label messages"' : '. messages'}
+                                      ". controls"`
+      } else {
+        return `${hasVisibleLabel ? ' "label controls"' : '. controls'}`
+      }
+    } else {
+      return `${hasVisibleLabel ? ' "label controls"' : '. controls'}
+              ${hasMessages ? ' ". messages"' : ''}`
+    }
+  }
+  // stacked layout -- in this case we could use a simple `Flex`
+  if (hasErrorMsgAndIsGroup) {
+    return `${hasVisibleLabel ? ' "label"' : ''}
+            ${hasMessages ? ' "messages"' : ''}
+            "controls"`
+  } else {
+    return `${hasVisibleLabel ? ' "label"' : ''}
+            "controls"
+            ${hasMessages ? ' "messages"' : ''}`
+  }
+}
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param componentTheme The theme variable object.
+ * @param params Additional parameters to customize the style.
+ * @param sharedTokens Shared token object that stores common values for the theme.
+ * @return The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['FormFieldLayout'],
+  params: StyleParams,
+  sharedTokens: SharedTokens
+): FormFieldLayoutStyle => {
+  const { inline, layout, vAlign, labelAlign, margin, messages } = params
+  const { hasMessages, hasVisibleLabel, hasErrorMsgAndIsGroup } = params
+  const cssMargin = calcSpacingFromShorthand(margin, {
+    ...sharedTokens.spacing,
+    ...sharedTokens.legacy.spacing
+  })
+  const isInlineLayout = layout === 'inline'
+
+  const hasNonEmptyMessages = messages?.reduce(
+    (acc, message) => acc || message.type !== 'screenreader-only',
+    false
+  )
+
+  // This is quite ugly, we should simplify it
+  const gridTemplateAreas = generateGridLayout(
+    isInlineLayout,
+    hasErrorMsgAndIsGroup,
+    hasVisibleLabel,
+    hasMessages
+  )
+  let gridTemplateColumns = '100%' // stacked layout
+  if (isInlineLayout) {
+    gridTemplateColumns = '1fr 3fr'
+    if (inline) {
+      gridTemplateColumns = 'auto 3fr'
+    }
+  }
+  const labelStyles = {
+    all: 'initial',
+    display: 'block',
+    gridArea: 'label',
+    color: componentTheme.textColor,
+    fontFamily: componentTheme.fontFamily,
+    fontWeight: componentTheme.fontWeight,
+    fontSize: componentTheme.fontSize,
+    lineHeight: componentTheme.lineHeight,
+    ...(isInlineLayout && {
+      margin: '0',
+      // when inline add a small padding between the label and the control
+      paddingRight: componentTheme.gapPrimitives,
+      // and use the horizontal alignment prop
+      [`@media screen and (width >= ${componentTheme.stackedOrInlineBreakpoint})`]:
+        {
+          textAlign: labelAlign
+        }
+    })
+  }
+
+  let alignItems = 'start'
+  if (vAlign == 'top') {
+    alignItems = 'start'
+  } else if (vAlign == 'middle') {
+    alignItems = 'center'
+  } else if (vAlign == 'bottom') {
+    alignItems = 'end'
+  }
+  return {
+    formFieldLayout: {
+      label: 'formFieldLayout',
+      all: 'initial',
+      border: '0',
+      padding: '0',
+      margin: cssMargin,
+      minWidth: '0',
+      direction: 'inherit',
+      textAlign: 'start',
+      opacity: 'inherit',
+      display: 'grid',
+      alignItems: alignItems,
+      verticalAlign: 'middle', // removes margin in inline layouts
+      gridTemplateColumns: gridTemplateColumns,
+      gridTemplateAreas: gridTemplateAreas,
+      [`@media screen and (width < ${componentTheme.stackedOrInlineBreakpoint})`]:
+        {
+          // for small screens use the stacked layout
+          gridTemplateColumns: '100%',
+          gridTemplateAreas: generateGridLayout(
+            false,
+            hasErrorMsgAndIsGroup,
+            hasVisibleLabel,
+            hasMessages
+          )
+        },
+      columnGap: '0.375rem',
+      rowGap: hasNonEmptyMessages ? componentTheme.gapPrimitives : '0',
+      width: '100%',
+      ...(inline && {
+        display: 'inline-grid',
+        width: 'auto'
+      })
+    },
+    formFieldLabel: {
+      label: 'formFieldLayout__label',
+      ...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: hasNonEmptyMessages ? '0' : componentTheme.gapPrimitives
+    },
+    formFieldChildren: {
+      label: 'formFieldLayout__children',
+      gridArea: 'controls',
+      // add a small margin between the message and the controls
+      ...(hasMessages && hasErrorMsgAndIsGroup && { marginTop: '0.375rem' }),
+      ...(isInlineLayout &&
+        inline && {
+          [`@media screen and (width >= ${componentTheme.stackedOrInlineBreakpoint})`]:
+            {
+              justifySelf: 'start'
+            }
+        })
+    },
+    requiredAsterisk: {
+      label: 'formFieldLayout__requiredAsterisk',
+      color: componentTheme.asteriskColor
+    }
+  }
+}
+
+export default generateStyle

package/src/FormFieldMessage/{index.tsx → v1/index.tsx}

@@ -28,7 +28,7 @@ import { ScreenReaderContent } from '@instructure/ui-a11y-content'
 
 import { IconWarningSolid } from '@instructure/ui-icons'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'

package/src/FormFieldMessage/{props.ts → v1/props.ts}

@@ -24,7 +24,10 @@
 
 import type { FormFieldMessageTheme } from '@instructure/shared-types'
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
-import type { FormMessageType, FormMessageChild } from '../FormPropTypes'
+import type {
+  FormMessageType,
+  FormMessageChild
+} from '../../utils/v1/FormPropTypes'
 
 type FormFieldMessageOwnProps = {
   variant?: FormMessageType

package/src/FormFieldMessage/{styles.ts → v1/styles.ts}

@@ -24,8 +24,7 @@
 
 import type { FormFieldMessageTheme } from '@instructure/shared-types'
 import type { FormFieldMessageProps, FormFieldMessageStyle } from './props'
-import type { FormMessageType } from '../FormPropTypes'
-
+import type { FormMessageType } from '../../utils/v1/FormPropTypes'
 /**
  * ---
  * private: true
@@ -54,7 +53,7 @@ const generateStyle = (
     errorIcon: {
       fontSize: componentTheme.fontSize,
       marginRight: componentTheme.errorIconMarginRight,
-      lineHeight: 1.25,
+      lineHeight: 1.25
     },
     formFieldMessage: {
       label: 'formFieldMessage',