@transferwise/components 46.30.1 → 46.31.0

package/src/dateLookup/DateLookup.tsx

@@ -12,7 +12,7 @@ import {
 } from '../common';
 import { isWithinRange, moveToWithinRange } from '../common/dateUtils';
 import ResponsivePanel from '../common/responsivePanel';
-
+import { WithInputAttributesProps, withInputAttributes } from '../inputs/contexts';
 import DateTrigger from './dateTrigger';
 import DayCalendar from './dayCalendar';
 import { getStartOfDay } from './getStartOfDay';
@@ -36,6 +36,8 @@ export interface DateLookupProps {
   onBlur?: () => void;
 }
 
+type DateLookupPropsWithInputAttributes = DateLookupProps & Partial<WithInputAttributesProps>;
+
 interface DateLookupState {
   selectedDate: Date | null;
   originalDate: Date | null;
@@ -48,9 +50,9 @@ interface DateLookupState {
   isMobile: boolean;
 }
 
-class DateLookup extends PureComponent<DateLookupProps, DateLookupState> {
-  declare props: DateLookupProps &
-    Required<Pick<DateLookupProps, keyof typeof DateLookup.defaultProps>>;
+class DateLookup extends PureComponent<DateLookupPropsWithInputAttributes, DateLookupState> {
+  declare props: DateLookupPropsWithInputAttributes &
+    Required<Pick<DateLookupPropsWithInputAttributes, keyof typeof DateLookup.defaultProps>>;
 
   static defaultProps = {
     value: null,
@@ -62,7 +64,7 @@ class DateLookup extends PureComponent<DateLookupProps, DateLookupState> {
     monthFormat: MonthFormat.LONG,
     disabled: false,
     clearable: false,
-  } satisfies Partial<DateLookupProps>;
+  } satisfies Partial<DateLookupPropsWithInputAttributes>;
 
   element = createRef<HTMLDivElement>();
   dropdown = createRef<HTMLDivElement>();
@@ -106,7 +108,7 @@ class DateLookup extends PureComponent<DateLookupProps, DateLookupState> {
     return null;
   }
 
-  componentDidUpdate(previousProps: DateLookupProps) {
+  componentDidUpdate(previousProps: DateLookupPropsWithInputAttributes) {
     if (this.props.value?.getTime() !== previousProps.value?.getTime() && this.state.open) {
       this.focusOn('.active');
     }
@@ -301,19 +303,25 @@ class DateLookup extends PureComponent<DateLookupProps, DateLookupState> {
     const { selectedDate, open } = this.state;
 
     const {
+      inputAttributes,
+      id: idProp,
+      'aria-labelledby': ariaLabelledByProp,
       size,
       placeholder,
       label,
-      'aria-labelledby': ariaLabelledBy,
       monthFormat,
       disabled,
       clearable,
       value,
     } = this.props;
+    const id = idProp ?? inputAttributes?.id;
+    const ariaLabelledBy = ariaLabelledByProp ?? inputAttributes?.['aria-labelledby'];
+
     return (
       <div
         ref={this.element}
-        id={this.props.id}
+        {...inputAttributes}
+        id={id}
         aria-labelledby={ariaLabelledBy}
         className="input-group"
         onKeyDown={this.handleKeyDown}
@@ -342,4 +350,11 @@ class DateLookup extends PureComponent<DateLookupProps, DateLookupState> {
   }
 }
 
-export default DateLookup;
+export const DateLookupWithoutInputAttributes = DateLookup;
+
+export default withInputAttributes(
+  DateLookup as React.ComponentType<DateLookupPropsWithInputAttributes>,
+  {
+    nonLabelable: true,
+  },
+);

package/src/dateLookup/DateLookup.view.spec.js

@@ -7,7 +7,7 @@ import DayCalendar from './dayCalendar';
 import MonthCalendar from './monthCalendar';
 import YearCalendar from './yearCalendar';
 
-import DateLookup from '.';
+import { DateLookupWithoutInputAttributes as DateLookup } from './DateLookup';
 
 mockMatchMedia();
 
@@ -51,7 +51,7 @@ describe('DateLookup view', () => {
   });
 
   it('passes props forward to open button', () => {
-    expect(+dateTrigger().prop('selectedDate')).toBe(+date);
+    expect(Number(dateTrigger().prop('selectedDate'))).toBe(Number(date));
     expect(dateTrigger().prop('size')).toBe('lg');
     expect(dateTrigger().prop('placeholder')).toBe('Asd..');
     expect(dateTrigger().prop('label')).toBe('Date..');
@@ -76,9 +76,9 @@ describe('DateLookup view', () => {
     });
 
     it('passes props forward to day calendar', () => {
-      expect(+dayCalendar().prop('selectedDate')).toBe(+date);
-      expect(+dayCalendar().prop('min')).toBe(+min);
-      expect(+dayCalendar().prop('max')).toBe(+max);
+      expect(Number(dayCalendar().prop('selectedDate'))).toBe(Number(date));
+      expect(Number(dayCalendar().prop('min'))).toBe(Number(min));
+      expect(Number(dayCalendar().prop('max'))).toBe(Number(max));
       expect(dayCalendar().prop('viewMonth')).toBe(11);
       expect(dayCalendar().prop('viewYear')).toBe(2018);
       expect(dayCalendar().prop('monthFormat')).toBe('long');
@@ -103,9 +103,9 @@ describe('DateLookup view', () => {
     });
 
     it('passes props forward to month calendar', () => {
-      expect(+monthCalendar().prop('selectedDate')).toBe(+date);
-      expect(+monthCalendar().prop('min')).toBe(+min);
-      expect(+monthCalendar().prop('max')).toBe(+max);
+      expect(Number(monthCalendar().prop('selectedDate'))).toBe(Number(date));
+      expect(Number(monthCalendar().prop('min'))).toBe(Number(min));
+      expect(Number(monthCalendar().prop('max'))).toBe(Number(max));
       expect(monthCalendar().prop('viewYear')).toBe(2018);
       expect(monthCalendar().prop('placeholder')).toBe('Asd..');
     });
@@ -129,9 +129,9 @@ describe('DateLookup view', () => {
     });
 
     it('passes props forward to year calendar', () => {
-      expect(+yearCalendar().prop('selectedDate')).toBe(+date);
-      expect(+yearCalendar().prop('min')).toBe(+min);
-      expect(+yearCalendar().prop('max')).toBe(+max);
+      expect(Number(yearCalendar().prop('selectedDate'))).toBe(Number(date));
+      expect(Number(yearCalendar().prop('min'))).toBe(Number(min));
+      expect(Number(yearCalendar().prop('max'))).toBe(Number(max));
       expect(yearCalendar().prop('viewYear')).toBe(2018);
       expect(yearCalendar().prop('placeholder')).toBe('Asd..');
     });

package/src/field/Field.spec.tsx

@@ -0,0 +1,95 @@
+import Info from '../info/Info';
+import { Input } from '../inputs/Input';
+import { mockMatchMedia, render, screen, userEvent } from '../test-utils';
+
+import { Field } from './Field';
+
+mockMatchMedia();
+
+describe('Field', () => {
+  it('should render label', () => {
+    render(
+      <Field label="Phone number">
+        <Input />
+      </Field>,
+    );
+
+    expect(screen.getByLabelText('Phone number')).toBeInTheDocument();
+    expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('should render help text if provided', () => {
+    render(
+      <Field label="Phone number" hint="This is help text">
+        <Input />
+      </Field>,
+    );
+
+    const textbox = screen.getByRole('textbox', { description: 'This is help text' });
+    expect(textbox).toBeInTheDocument();
+    expect(textbox).not.toBeInvalid();
+  });
+
+  it('should render error text if provided', () => {
+    render(
+      <Field label="Phone number" error="This is error text">
+        <Input />
+      </Field>,
+    );
+
+    const textbox = screen.getByRole('textbox', { description: 'This is error text' });
+    expect(textbox).toBeInTheDocument();
+    expect(textbox).toBeInvalid();
+  });
+
+  it('should prefer error text over help text if both are provided', () => {
+    render(
+      <Field label="Phone number" error="This is error text" hint="This is help text">
+        <Input />
+      </Field>,
+    );
+
+    expect(screen.getByRole('textbox', { description: 'This is error text' })).toBeInTheDocument();
+    expect(screen.queryByText('This is help text')).not.toBeInTheDocument();
+  });
+
+  it('avoids triggering button within label inadvertently', async () => {
+    const handleClick = jest.fn();
+
+    render(
+      <Field
+        label={
+          <span>
+            Phone number{' '}
+            <Info content="Further information explained in detail." onClick={handleClick} />
+          </span>
+        }
+      >
+        <Input />
+      </Field>,
+    );
+
+    const button = screen.getByRole('button');
+    button.addEventListener('click', handleClick);
+
+    const label = screen.getByText('Phone number');
+    userEvent.click(label);
+
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('allows nesting-based label association', async () => {
+    const handleClick = jest.fn();
+
+    render(
+      <Field id={null} label="Phone number">
+        <Input onClick={handleClick} />
+      </Field>,
+    );
+
+    expect(screen.getByRole('textbox')).not.toHaveAttribute('id');
+
+    const label = screen.getByText('Phone number');
+    userEvent.click(label);
+  });
+});

package/src/field/Field.story.tsx

@@ -0,0 +1,59 @@
+import { useState } from 'react';
+
+import { Input } from '../inputs/Input';
+import { Field } from './Field';
+
+export default {
+  component: Field,
+  title: 'Field',
+};
+
+export const Basic = () => {
+  const [value, setValue] = useState<string | undefined>('This is some text');
+  return (
+    <Field label="Phone number">
+      <Input value={value} onChange={({ target }) => setValue(target.value)} />
+    </Field>
+  );
+};
+
+export const WithErrorMessage = () => {
+  const [value, setValue] = useState<string | undefined>('This is some text');
+  return (
+    <Field label="Phone number" error="This is a required field">
+      <Input value={value} onChange={({ target }) => setValue(target.value)} />
+    </Field>
+  );
+};
+
+export const WithHelp = () => {
+  const [value, setValue] = useState<string | undefined>('This is some text');
+  return (
+    <Field label="Phone number" hint="This is a helpful message">
+      <Input value={value} onChange={({ target }) => setValue(target.value)} />
+    </Field>
+  );
+};
+
+export const WithHelpAndErrorOnBlur = () => {
+  const [value, setValue] = useState<string | undefined>('This is some text');
+  const [error, setError] = useState<string | undefined>(undefined);
+  return (
+    <Field label="Phone number" hint="Please include country code" error={error}>
+      <Input
+        value={value}
+        onChange={({ target }) => {
+          setValue(target.value);
+          setError(undefined);
+        }}
+        onBlur={() => {
+          if (!value) {
+            setError('This is a required field');
+          } else {
+            setError(undefined);
+          }
+        }}
+      />
+    </Field>
+  );
+};

package/src/field/Field.tsx

@@ -0,0 +1,70 @@
+import { useId } from '@radix-ui/react-id';
+import classNames from 'classnames';
+
+import { Sentiment } from '../common';
+import InlineAlert from '../inlineAlert/InlineAlert';
+import {
+  FieldLabelIdContextProvider,
+  InputDescribedByProvider,
+  InputIdContextProvider,
+  InputInvalidProvider,
+} from '../inputs/contexts';
+import { Label } from '../label/Label';
+
+export type FieldProps = {
+  /** `null` disables auto-generating the `id` attribute, falling back to nesting-based label association over setting `htmlFor` explicitly. */
+  id?: string | null;
+  label: React.ReactNode;
+  hint?: React.ReactNode;
+  error?: React.ReactNode;
+  className?: string;
+  children?: React.ReactNode;
+};
+
+export const Field = ({ id, label, hint, error, className, children }: FieldProps) => {
+  const hasError = Boolean(error);
+  const hasHint = Boolean(hint) && !hasError;
+
+  const labelId = useId();
+
+  const fallbackInputId = useId(); // TODO: Use `React.useId()` when react>=18
+  const inputId = id !== null ? id ?? fallbackInputId : undefined;
+
+  const descriptionId = useId(); // TODO: Use `React.useId()` when react>=18
+
+  return (
+    <FieldLabelIdContextProvider value={labelId}>
+      <InputIdContextProvider value={inputId}>
+        <InputDescribedByProvider value={hasError || hasHint ? descriptionId : undefined}>
+          <InputInvalidProvider value={hasError}>
+            <div
+              className={classNames(
+                'form-group d-block',
+                {
+                  'has-error': hasError,
+                  'has-info': hasHint,
+                },
+                className,
+              )}
+            >
+              <Label id={labelId} htmlFor={inputId}>
+                {label}
+                {children}
+              </Label>
+              {hasHint && (
+                <InlineAlert type={Sentiment.NEUTRAL} id={descriptionId}>
+                  {hint}
+                </InlineAlert>
+              )}
+              {hasError && (
+                <InlineAlert type={Sentiment.NEGATIVE} id={descriptionId}>
+                  {error}
+                </InlineAlert>
+              )}
+            </div>
+          </InputInvalidProvider>
+        </InputDescribedByProvider>
+      </InputIdContextProvider>
+    </FieldLabelIdContextProvider>
+  );
+};

package/src/index.ts

@@ -21,6 +21,7 @@ export type { DateLookupProps } from './dateLookup';
 export type { DecisionProps } from './decision/Decision';
 export type { DimmerProps } from './dimmer';
 export type { EmphasisProps } from './emphasis';
+export type { FieldProps } from './field/Field';
 export type { InfoProps } from './info';
 export type { InputWithDisplayFormatProps } from './inputWithDisplayFormat';
 export type { InputProps } from './inputs/Input';
@@ -37,6 +38,7 @@ export type {
 } from './inputs/SelectInput';
 export type { TextAreaProps } from './inputs/TextArea';
 export type { InstructionsListProps } from './instructionsList';
+export type { LabelProps } from './label/Label';
 export type { LoaderProps } from './loader';
 export type { MarkdownProps } from './markdown';
 export type { ModalProps } from './modal';
@@ -103,6 +105,7 @@ export { default as Drawer } from './drawer';
 export { default as DropFade } from './dropFade';
 export { default as Emphasis } from './emphasis';
 export { default as FlowNavigation } from './flowNavigation/FlowNavigation';
+export { Field } from './field/Field';
 export { default as Header } from './header';
 export { default as Image } from './image';
 export { default as Info } from './info';
@@ -118,6 +121,7 @@ export {
 } from './inputs/SelectInput';
 export { TextArea } from './inputs/TextArea';
 export { default as InstructionsList } from './instructionsList';
+export { Label } from './label/Label';
 export { default as Link } from './link';
 export { default as ListItem } from './listItem';
 export { default as Loader } from './loader';

package/src/inputs/Input.tsx

@@ -3,9 +3,9 @@ import { forwardRef } from 'react';
 
 import { SizeLarge, SizeMedium, SizeSmall } from '../common';
 import { Merge } from '../utils';
-
+import { inputClassNameBase } from './_common';
+import { useInputAttributes } from './contexts';
 import { useInputPaddings } from './InputGroup';
-import { formControlClassNameBase } from './_common';
 
 export interface InputProps
   extends Merge<
@@ -21,17 +21,19 @@ export const Input = forwardRef(function Input(
   { size = 'auto', shape = 'rectangle', className, ...restProps }: InputProps,
   reference: React.ForwardedRef<HTMLInputElement>,
 ) {
+  const inputAttributes = useInputAttributes();
   const inputPaddings = useInputPaddings();
 
   return (
     <input
       ref={reference}
-      className={classNames(className, formControlClassNameBase({ size }), 'np-input', {
+      className={classNames(className, inputClassNameBase({ size }), 'np-input', {
         'np-input--shape-rectangle': shape === 'rectangle',
         'np-input--shape-pill': shape === 'pill',
       })}
       // eslint-disable-next-line react/forbid-dom-props
       style={inputPaddings}
+      {...inputAttributes}
       {...restProps}
     />
   );

package/src/inputs/SelectInput.spec.tsx

@@ -4,6 +4,7 @@ import userEvent from '@testing-library/user-event';
 import { render, mockMatchMedia, mockResizeObserver } from '../test-utils';
 
 import { SelectInput } from './SelectInput';
+import { Field } from '../field/Field';
 
 mockMatchMedia();
 mockResizeObserver();
@@ -227,4 +228,13 @@ describe('SelectInput', () => {
     const trigger = screen.getAllByRole('button')[0];
     expect(trigger).toHaveAttribute('id', 'custom');
   });
+
+  it('supports `Field` for labeling', () => {
+    render(
+      <Field label="Currency">
+        <SelectInput items={[{ type: 'option', value: 'USD' }]} value="USD" />
+      </Field>,
+    );
+    expect(screen.getByLabelText('Currency')).toHaveTextContent('USD');
+  });
 });

package/src/inputs/SelectInput.tsx

@@ -13,12 +13,13 @@ import { Breakpoint } from '../common/propsValues/breakpoint';
 import dateTriggerMessages from '../dateLookup/dateTrigger/DateTrigger.messages';
 import { Merge } from '../utils';
 
-import { InputGroup } from './InputGroup';
-import { SearchInput } from './SearchInput';
-import messages from './SelectInput.messages';
 import { BottomSheet } from './_BottomSheet';
 import { ButtonInput } from './_ButtonInput';
 import { Popover } from './_Popover';
+import { useInputAttributes } from './contexts';
+import { InputGroup } from './InputGroup';
+import { SearchInput } from './SearchInput';
+import messages from './SelectInput.messages';
 
 function searchableString(value: string) {
   return value.trim().replace(/\s+/gu, ' ').normalize('NFKC').toLowerCase();
@@ -221,7 +222,7 @@ function SelectInputClearButton({ className, onClick }: SelectInputClearButtonPr
 const noop = () => {};
 
 export function SelectInput<T = string, M extends boolean = false>({
-  id,
+  id: idProp,
   name,
   multiple,
   placeholder,
@@ -242,6 +243,9 @@ export function SelectInput<T = string, M extends boolean = false>({
   onClose,
   onClear,
 }: SelectInputProps<T, M>) {
+  const inputAttributes = useInputAttributes();
+  const id = idProp ?? inputAttributes.id;
+
   const [open, setOpen] = useState(false);
 
   const initialized = useRef(false);
@@ -308,6 +312,7 @@ export function SelectInput<T = string, M extends boolean = false>({
                     ref(node);
                     triggerRef.current = node;
                   },
+                  ...inputAttributes,
                   id,
                   ...mergeProps(
                     {

package/src/inputs/TextArea.tsx

@@ -2,8 +2,8 @@ import classNames from 'classnames';
 import { forwardRef } from 'react';
 
 import { Merge } from '../utils';
-
-import { formControlClassNameBase } from './_common';
+import { inputClassNameBase } from './_common';
+import { useInputAttributes } from './contexts';
 
 export interface TextAreaProps
   extends Merge<
@@ -17,10 +17,13 @@ export const TextArea = forwardRef(function TextArea(
   { className, ...restProps }: TextAreaProps,
   reference: React.ForwardedRef<HTMLTextAreaElement>,
 ) {
+  const inputAttributes = useInputAttributes();
+
   return (
     <textarea
       ref={reference}
-      className={classNames(className, formControlClassNameBase(), 'np-text-area')}
+      className={classNames(className, inputClassNameBase(), 'np-text-area')}
+      {...inputAttributes}
       {...restProps}
     />
   );

package/src/inputs/_ButtonInput.tsx

@@ -2,7 +2,7 @@ import classNames from 'classnames';
 import { forwardRef } from 'react';
 
 import { useInputPaddings } from './InputGroup';
-import { formControlClassNameBase } from './_common';
+import { inputClassNameBase } from './_common';
 
 export interface ButtonInputProps extends React.ComponentPropsWithRef<'button'> {
   size?: 'sm' | 'md' | 'lg';
@@ -18,7 +18,7 @@ export const ButtonInput = forwardRef(function ButtonInput(
     <button
       ref={ref}
       type="button"
-      className={classNames(className, formControlClassNameBase({ size }), 'np-button-input')}
+      className={classNames(className, inputClassNameBase({ size }), 'np-button-input')}
       // eslint-disable-next-line react/forbid-dom-props
       style={{ ...inputPaddings, ...style }}
       {...restProps}

package/src/inputs/_common.ts

@@ -2,11 +2,11 @@ import classNames from 'classnames';
 
 import { SizeLarge, SizeMedium, SizeSmall } from '../common';
 
-export type FormControlPropsBase = {
+export type InputPropsBase = {
   size?: 'auto' | SizeSmall | SizeMedium | SizeLarge;
 };
 
-export function formControlClassNameBase({ size = 'auto' }: FormControlPropsBase = {}) {
+export function inputClassNameBase({ size = 'auto' }: InputPropsBase = {}) {
   return classNames(
     'form-control', // TODO: Deprecate
     'np-form-control',

package/src/inputs/contexts.tsx

@@ -0,0 +1,45 @@
+import { createContext, useContext } from 'react';
+
+const FieldLabelIdContext = createContext<string | undefined>(undefined);
+export const FieldLabelIdContextProvider = FieldLabelIdContext.Provider;
+
+const InputIdContext = createContext<string | undefined>(undefined);
+export const InputIdContextProvider = InputIdContext.Provider;
+
+const InputDescribedByContext = createContext<string | undefined>(undefined);
+export const InputDescribedByProvider = InputDescribedByContext.Provider;
+
+const InputInvalidContext = createContext<boolean | undefined>(undefined);
+export const InputInvalidProvider = InputInvalidContext.Provider;
+
+interface UseInputAttributesArgs {
+  /** Set this to `true` if the underlying element is not directly [labelable as per the HTML specification](https://html.spec.whatwg.org/multipage/forms.html#category-label). */
+  nonLabelable?: boolean;
+}
+
+export function useInputAttributes({ nonLabelable }: UseInputAttributesArgs = {}) {
+  const labelId = useContext(FieldLabelIdContext);
+  return {
+    id: useContext(InputIdContext),
+    'aria-labelledby': nonLabelable ? labelId : undefined,
+    'aria-describedby': useContext(InputDescribedByContext),
+    'aria-invalid': useContext(InputInvalidContext),
+  } satisfies React.HTMLAttributes<HTMLElement>;
+}
+
+export interface WithInputAttributesProps {
+  inputAttributes: ReturnType<typeof useInputAttributes>;
+}
+
+export function withInputAttributes<T extends Partial<WithInputAttributesProps>>(
+  Component: React.ComponentType<T>,
+  args?: UseInputAttributesArgs,
+) {
+  function ComponentWithInputAttributes(props: Omit<T, keyof WithInputAttributesProps>) {
+    return <Component inputAttributes={useInputAttributes(args)} {...(props as T)} />;
+  }
+
+  ComponentWithInputAttributes.displayName = `withInputAttributes(${Component.displayName || Component.name || 'Component'})`;
+
+  return ComponentWithInputAttributes;
+}

package/src/label/Label.spec.tsx

@@ -0,0 +1,26 @@
+import { Input } from '../inputs/Input';
+import { render, screen } from '../test-utils';
+import { Label } from './Label';
+
+describe('Label', () => {
+  it('renders string labels', () => {
+    render(
+      <Label>
+        Phone number
+        <Input readOnly />
+      </Label>,
+    );
+
+    expect(screen.getByLabelText('Phone number')).toBeInTheDocument();
+  });
+  it('renders node type labels', () => {
+    render(
+      <Label>
+        <span>Phone number</span>
+        <Input readOnly />
+      </Label>,
+    );
+
+    expect(screen.getByLabelText('Phone number')).toBeInTheDocument();
+  });
+});

package/src/label/Label.story.tsx

@@ -0,0 +1,37 @@
+import { useState } from 'react';
+
+import Info from '../info/Info';
+import { Input } from '../inputs/Input';
+import { Label } from './Label';
+
+export default {
+  component: Label,
+  title: 'Label',
+};
+
+export const Basic = () => {
+  const [value, setValue] = useState<string | undefined>('This is some text');
+  return (
+    <Label>
+      Phone number
+      <Input value={value} id="input" onChange={({ target }) => setValue(target.value)} />
+    </Label>
+  );
+};
+
+export const WithInfo = () => {
+  const [value, setValue] = useState<string | undefined>('This is some text');
+  return (
+    <Label>
+      <span className="d-flex">
+        Phone number{' '}
+        <Info
+          content="This is some help in popover"
+          aria-label="The aria label"
+          className="m-l-1"
+        />
+      </span>
+      <Input value={value} id="input" onChange={({ target }) => setValue(target.value)} />
+    </Label>
+  );
+};