feat: Allow positional placement of endSlot in TextField (#899)

* chore: Allow npm v11+

* feat: Allow positional placement of `endSlot` in `TextField`

* chore: Update comment

* chore: Correct type usage

* chore: Fix endslot visibility

* test: Add tests for `endSlotPosition`

Author: scottlovegrove

package-lock.json

@@ -29,7 +29,7 @@
     ],
     "engines": {
         "node": "^16.0.0 || ^18.0.0 || ^20.0.0 || ^21.0.0",
-        "npm": "^8.3.0 || ^9.0.0 || ^10.0.0"
+        "npm": "^8.3.0 || ^9.0.0 || ^10.0.0 || ^11.0.0"
     },
     "scripts": {
         "postinstall": "patch-package",

package.json

@@ -213,7 +213,23 @@ export type BaseFieldProps = WithEnhancedClassName &
          * @default 'below'
          */
         characterCountPosition?: 'below' | 'inline' | 'hidden'
-    }
+    } & (
+        | {
+              supportsStartAndEndSlots?: false
+              endSlot?: never
+              endSlotPosition?: never
+          }
+        | {
+              supportsStartAndEndSlots: true
+              endSlot?: React.ReactElement | string | number
+              /**
+               * This is solely for `bordered` variants of TextField. When set to `bottom` (the default),
+               * the endSlot will be placed inline with the input field. When set to `fullHeight`, the endSlot
+               * will be placed to the side of both the input field and the label.
+               */
+              endSlotPosition?: 'bottom' | 'fullHeight'
+          }
+    )
 
 type FieldComponentProps<T extends HTMLElement> = Omit<
     BaseFieldProps,
@@ -239,6 +255,8 @@ function BaseField({
     'aria-describedby': originalAriaDescribedBy,
     id: originalId,
     characterCountPosition = 'below',
+    endSlot,
+    endSlotPosition = 'bottom',
 }: BaseFieldProps & BaseFieldVariantProps & WithEnhancedClassName) {
     const id = useId(originalId)
     const messageId = useId()
@@ -302,36 +320,44 @@ function BaseField({
     return (
         <Stack space="xsmall" hidden={hidden}>
             <Box
+                display="flex"
+                flexDirection="row"
                 className={[
                     className,
                     styles.container,
                     tone === 'error' ? styles.error : null,
                     variant === 'bordered' ? styles.bordered : null,
                 ]}
                 maxWidth={maxWidth}
+                alignItems="center"
             >
-                {label || auxiliaryLabel ? (
-                    <Box
-                        as="span"
-                        display="flex"
-                        justifyContent="spaceBetween"
-                        alignItems="flexEnd"
-                    >
-                        <Text
-                            size={variant === 'bordered' ? 'caption' : 'body'}
-                            as="label"
-                            htmlFor={id}
+                <Box flexGrow={1}>
+                    {label || auxiliaryLabel ? (
+                        <Box
+                            as="span"
+                            display="flex"
+                            justifyContent="spaceBetween"
+                            alignItems="flexEnd"
                         >
-                            {label ? <span className={styles.primaryLabel}>{label}</span> : null}
-                        </Text>
-                        {auxiliaryLabel ? (
-                            <Box className={styles.auxiliaryLabel} paddingLeft="small">
-                                {auxiliaryLabel}
-                            </Box>
-                        ) : null}
-                    </Box>
-                ) : null}
-                {children(childrenProps)}
+                            <Text
+                                size={variant === 'bordered' ? 'caption' : 'body'}
+                                as="label"
+                                htmlFor={id}
+                            >
+                                {label ? (
+                                    <span className={styles.primaryLabel}>{label}</span>
+                                ) : null}
+                            </Text>
+                            {auxiliaryLabel ? (
+                                <Box className={styles.auxiliaryLabel} paddingLeft="small">
+                                    {auxiliaryLabel}
+                                </Box>
+                            ) : null}
+                        </Box>
+                    ) : null}
+                    {children(childrenProps)}
+                </Box>
+                {endSlot && endSlotPosition === 'fullHeight' ? endSlot : null}
             </Box>
 
             {message || characterCount ? (

src/base-field/base-field.tsx

@@ -4,7 +4,14 @@ import { Box } from '../box'
 import styles from './select-field.module.css'
 
 interface SelectFieldProps
-    extends Omit<FieldComponentProps<HTMLSelectElement>, 'maxLength' | 'characterCountPosition'>,
+    extends Omit<
+            FieldComponentProps<HTMLSelectElement>,
+            | 'maxLength'
+            | 'characterCountPosition'
+            | 'endSlot'
+            | 'supportsStartAndEndSlots'
+            | 'endSlotPosition'
+        >,
         BaseFieldVariantProps {}
 
 const SelectField = React.forwardRef<HTMLSelectElement, SelectFieldProps>(function SelectField(

src/select-field/select-field.tsx

@@ -5,7 +5,9 @@ import { BaseField, BaseFieldVariantProps, FieldComponentProps } from '../base-f
 import { Box } from '../box'
 import styles from './text-area.module.css'
 
-interface TextAreaProps extends FieldComponentProps<HTMLTextAreaElement>, BaseFieldVariantProps {
+interface TextAreaProps
+    extends FieldComponentProps<HTMLTextAreaElement>,
+        Omit<BaseFieldVariantProps, 'supportsStartAndEndSlots' | 'endSlot' | 'endSlotPosition'> {
     /**
      * The number of visible text lines for the text area.
      *

src/text-area/text-area.tsx

@@ -4,7 +4,7 @@ import { TextField } from './'
 import { Box } from '../box'
 import { Stack } from '../stack'
 import { Text } from '../text'
-import { Button } from '../button'
+import { Button, IconButton } from '../button'
 import { Tooltip } from '../tooltip'
 
 import { selectWithNone } from '../utils/storybook-helper'
@@ -256,7 +256,7 @@ export function ClearButtonIcon() {
 export function ClearButtonExample({ slot }) {
     const [value, setValue] = React.useState('')
     const clearButton = (
-        <Button
+        <IconButton
             variant="quaternary"
             icon={<ClearButtonIcon />}
             aria-label="Clear search"
@@ -325,6 +325,38 @@ Hence, the description is never needed when the field is not focused anyway.
     </Story>
 </Canvas>
 
+## Variants
+
+The `variant` prop is used to change the style of the text field. The default variant is `default`. The other variant is `bordered`.
+
+export function WithBorderedExample() {
+    return (
+        <TextField label="Company name" placeholder="Text field with a border" variant="bordered" />
+    )
+}
+
+export function WithBorderedAndEndSlotExample({ endSlotPosition = 'fullHeight' } = {}) {
+    return (
+        <TextField
+            label="Company name"
+            placeholder="Text field with a border and end slot"
+            variant="bordered"
+            endSlot={<IconButton variant="primary" icon="😄" aria-label="Say cheese!" />}
+            endSlotPosition={endSlotPosition}
+        />
+    )
+}
+
+<Canvas withToolbar>
+    <Story name="Bordered variant">
+        <Stack space="xxlarge" dividers="secondary">
+            <WithBorderedExample />
+            <WithBorderedAndEndSlotExample />
+            <WithBorderedAndEndSlotExample endSlotPosition="bottom" />
+        </Stack>
+    </Story>
+</Canvas>
+
 ## Max length
 
 The `maxLength` prop is used to limit the number of characters that the user can input. When the user tries to input more characters than the maximum allowed, the field won't accept the input.

src/text-field/text-field.stories.mdx

@@ -1,6 +1,6 @@
 import * as React from 'react'
 import { render, screen } from '@testing-library/react'
-import { TextField } from './'
+import { TextField, TextFieldProps } from './'
 import userEvent from '@testing-library/user-event'
 import { axe } from 'jest-axe'
 
@@ -247,6 +247,39 @@ describe('TextField', () => {
         })
     })
 
+    describe('endSlotPosition', () => {
+        test.each<TextFieldProps['endSlotPosition']>(['bottom', 'fullHeight', undefined])(
+            'renders the end slot for default variant when endSlotPosition is %s',
+            (endSlotPosition) => {
+                render(
+                    <TextField
+                        label="Whatʼs your name?"
+                        maxLength={30}
+                        endSlot="Kwijibo"
+                        endSlotPosition={endSlotPosition}
+                    />,
+                )
+                expect(screen.getByText('Kwijibo')).toBeInTheDocument()
+            },
+        )
+
+        test.each<TextFieldProps['endSlotPosition']>(['bottom', 'fullHeight', undefined])(
+            'renders the end slot for bordered variant when endSlotPosition is %s',
+            (endSlotPosition) => {
+                render(
+                    <TextField
+                        label="Whatʼs your name?"
+                        maxLength={30}
+                        endSlot="Kwijibo"
+                        endSlotPosition={endSlotPosition}
+                        variant="bordered"
+                    />,
+                )
+                expect(screen.getByText('Kwijibo')).toBeInTheDocument()
+            },
+        )
+    })
+
     describe('character count', () => {
         it('renders the character count element when characterCountPosition is "below"', () => {
             render(

src/text-field/text-field.test.tsx

@@ -8,7 +8,7 @@ import { useMergeRefs } from 'use-callback-ref'
 type TextFieldType = 'email' | 'search' | 'tel' | 'text' | 'url'
 
 interface TextFieldProps
-    extends Omit<FieldComponentProps<HTMLInputElement>, 'type'>,
+    extends Omit<FieldComponentProps<HTMLInputElement>, 'type' | 'supportsStartAndEndSlots'>,
         BaseFieldVariantProps,
         Pick<BaseFieldProps, 'characterCountPosition'> {
     type?: TextFieldType
@@ -40,6 +40,7 @@ const TextField = React.forwardRef<HTMLInputElement, TextFieldProps>(function Te
         endSlot,
         onChange: originalOnChange,
         characterCountPosition = 'below',
+        endSlotPosition = 'bottom',
         ...props
     },
     ref,
@@ -52,6 +53,10 @@ const TextField = React.forwardRef<HTMLInputElement, TextFieldProps>(function Te
         internalRef.current?.focus()
     }
 
+    const displayEndSlot =
+        endSlot &&
+        (variant === 'default' || (variant === 'bordered' && endSlotPosition === 'bottom'))
+
     return (
         <BaseField
             variant={variant}
@@ -66,6 +71,9 @@ const TextField = React.forwardRef<HTMLInputElement, TextFieldProps>(function Te
             hidden={hidden}
             aria-describedby={ariaDescribedBy}
             characterCountPosition={characterCountPosition}
+            supportsStartAndEndSlots
+            endSlot={endSlot}
+            endSlotPosition={variant === 'bordered' ? endSlotPosition : undefined}
         >
             {({ onChange, characterCountElement, ...extraProps }) => (
                 <Box
@@ -100,15 +108,15 @@ const TextField = React.forwardRef<HTMLInputElement, TextFieldProps>(function Te
                             onChange?.(event)
                         }}
                     />
-                    {endSlot || characterCountElement ? (
+                    {displayEndSlot || characterCountElement ? (
                         <Box
                             className={styles.slot}
                             display="flex"
                             marginRight={variant === 'bordered' ? '-xsmall' : 'xsmall'}
                             marginLeft={variant === 'bordered' ? 'xsmall' : '-xsmall'}
                         >
                             {characterCountElement}
-                            {endSlot}
+                            {displayEndSlot ? endSlot : null}
                         </Box>
                     ) : null}
                 </Box>