@transferwise/components 46.103.1 → 46.105.0

package/src/listItem/ListItem.tsx

@@ -0,0 +1,440 @@
+import {
+  useContext,
+  useId,
+  useMemo,
+  useState,
+  type PropsWithChildren,
+  type ReactNode,
+} from 'react';
+import { Typography } from '../common';
+import Body from '../body';
+import { AdditionalInfo } from './AdditionalInfo';
+import { IconButton, type ListItemIconButtonProps } from './IconButton';
+import { Checkbox, type ListItemCheckboxProps } from './Checkbox';
+import { Navigation, type ListItemNavigationProps } from './Navigation';
+import { clsx } from 'clsx';
+import { Button, type ListItemButtonProps } from './Button';
+import { Radio, type ListItemRadioProps } from './Radio';
+import { Switch, type ListItemSwitchProps } from './Switch';
+import { AvatarLayout } from './AvatarLayout';
+import { AvatarView } from './AvatarView';
+import { Image } from './Image';
+import { Prompt } from './Prompt';
+import { PrimitiveAnchor, type PrimitiveAnchorProps } from '../primitives';
+import {
+  ListItemContext,
+  type ListItemContextData,
+  type ListItemMediaSize,
+} from './ListItemContext';
+
+export type ListItemTypes =
+  | 'non-interactive'
+  | 'navigation'
+  | 'radio'
+  | 'checkbox'
+  | 'switch'
+  | 'button'
+  | 'icon-button';
+
+export type ListItemControlProps =
+  | ListItemNavigationProps
+  | ListItemCheckboxProps
+  | ListItemButtonProps
+  | ListItemIconButtonProps
+  | ListItemRadioProps
+  | ListItemSwitchProps;
+
+export type ListItemProps = {
+  as?: 'li' | 'div';
+  /**
+   * Swaps vertical hierarchy of title and subtitle and their corresponding right values.
+   */
+  inverted?: boolean;
+  disabled?: boolean;
+  /**
+   * Highlights the list item as an action to be taken or already taken. <br />
+   */
+  spotlight?: 'active' | 'inactive';
+  title: ReactNode;
+  subtitle?: ReactNode;
+  /**
+   * Requires `<ListItem.AdditionalInfo />` component as a sole child. <br />
+   * Can be only rendered if `subtitle` is also provided.
+   */
+  additionalInfo?: ReactNode;
+  valueTitle?: ReactNode;
+  valueSubtitle?: ReactNode;
+  /**
+   * Requires one of the following as a sole child: <br />
+   * `<ListItem.AvatarView />`,
+   * `<ListItem.AvatarLayout />` or
+   * `<ListItem.Image />`
+   */
+  media?: ReactNode;
+  /**
+   * Requires one of the following as a sole child: <br/>
+   * `<ListItem.Button />`, <br/>
+   * `<ListItem.Checkbox />`, <br/>
+   * `<ListItem.IconButton />`, <br/>
+   * `<ListItem.Navigation />`, <br/>
+   * `<ListItem.Radio />`, or
+   * `<ListItem.Switch />`
+   */
+  control?: ReactNode;
+  /**
+   * Requires `<ListItem.Prompt />` component as a sole child.
+   */
+  prompt?: ReactNode;
+  className?: string;
+  /**
+   * A number between `0–100` which resolves to a `fr` value of a `grid-template-columns` declaration. E.g. `valueColumnWidth={25}` will result in a `75fr 25fr`. <br />
+   * Controls the width ratio of left side content (title and subtitle) to the right side content.
+   */
+  valueColumnWidth?: number;
+  id?: string;
+};
+
+/**
+ * @see [Design documentation](https://wise.design/components/list-item)
+ * @see [Storybook documentation](https://storybook.wise.design/?path=/docs/content-listitem--docs)
+ */
+export const ListItem = ({
+  as: ListItemElement = 'li',
+  title,
+  subtitle,
+  additionalInfo,
+  prompt,
+  inverted,
+  media,
+  spotlight,
+  valueTitle,
+  valueSubtitle,
+  control = null,
+  disabled,
+  className,
+  valueColumnWidth,
+  id,
+}: ListItemProps) => {
+  const idPrefix = useId();
+  const [controlProps, setControlProps] = useState<ListItemControlProps>({});
+  const [controlType, setControlType] = useState<ListItemTypes>('non-interactive');
+  const [mediaSize, setMediaSize] = useState<ListItemMediaSize | undefined>();
+
+  const ids: ListItemContextData['ids'] = {
+    title: `${idPrefix}_title`,
+    ...(subtitle ? { subtitle: `${idPrefix}_subtitle` } : {}),
+    ...(valueTitle ? { valueTitle: `${idPrefix}_value-title` } : {}),
+    ...(valueSubtitle ? { valueSubtitle: `${idPrefix}_value-subtitle` } : {}),
+    control: `${idPrefix}_control`,
+    ...(prompt ? { prompt: `${idPrefix}_prompt` } : {}),
+    ...(additionalInfo ? { additionalInfo: `${idPrefix}_additional-info` } : {}),
+  };
+
+  const isPartiallyInteractive = Boolean(
+    (controlType === 'button' || controlType === 'icon-button') &&
+      (controlProps as ListItemButtonProps | ListItemIconButtonProps)?.partiallyInteractive,
+  );
+  const isFullyInteractive = controlType !== 'non-interactive' && !isPartiallyInteractive;
+  const isButtonAsLink =
+    (controlType === 'button' || controlType === 'icon-button') &&
+    Boolean((controlProps as ListItemButtonProps | ListItemIconButtonProps)?.href);
+
+  const titlesAndValues = [
+    inverted ? ids.subtitle : ids.title,
+    inverted ? ids.title : ids.subtitle,
+    inverted ? ids.valueSubtitle : ids.valueTitle,
+    inverted ? ids.valueTitle : ids.valueSubtitle,
+  ].join(' ');
+  const additionalInfoPrompt = [ids.additionalInfo, ids.prompt].filter(Boolean).join(' ');
+
+  const describedByIds = useMemo(() => {
+    return isFullyInteractive && !isButtonAsLink
+      ? additionalInfoPrompt
+      : `${titlesAndValues} ${additionalInfoPrompt}`;
+  }, [isFullyInteractive]);
+
+  const listItemContext = useMemo(
+    () => ({
+      setControlType,
+      setControlProps,
+      setMediaSize,
+      ids,
+      props: { disabled, inverted },
+      mediaSize,
+      describedByIds,
+    }),
+    [describedByIds, mediaSize],
+  );
+  const gridColumnsStyle = {
+    '--wds-list-item-body-left': valueColumnWidth ? `${100 - valueColumnWidth}fr` : '50fr',
+    '--wds-list-item-body-right': valueColumnWidth ? `${valueColumnWidth}fr` : '50fr',
+  } as React.CSSProperties;
+
+  const getFeatureClassName = () => {
+    const partials = [];
+    const hasMedia = Boolean(media);
+    const hasControl = Boolean(control);
+    const hasInfo = Boolean(additionalInfo);
+    const hasPrompt = Boolean(prompt);
+
+    /* eslint-disable functional/immutable-data */
+    if (hasMedia && hasControl) {
+      partials.push('wds-list-item-hasMedia-hasControl');
+    }
+
+    if (hasMedia && !hasControl) {
+      partials.push('wds-list-item-hasMedia-noControl');
+    }
+
+    if (!hasMedia && hasControl) {
+      partials.push('wds-list-item-noMedia-hasControl');
+    }
+
+    if (!hasMedia && !hasControl) {
+      partials.push('wds-list-item-noMedia-noControl');
+    }
+
+    if (hasInfo && hasPrompt) {
+      partials.push('wds-list-item-hasInfo-hasPrompt');
+    }
+    if (hasInfo && !hasPrompt) {
+      partials.push('wds-list-item-hasInfo-noPrompt');
+    }
+    if (!hasInfo && hasPrompt) {
+      partials.push('wds-list-item-noInfo-hasPrompt');
+    }
+    if (!hasInfo && !hasPrompt) {
+      partials.push('wds-list-item-noInfo-noPrompt');
+    }
+    /* eslint-enable functional/immutable-data */
+
+    return partials.join(' ');
+  };
+
+  return (
+    <ListItemContext.Provider value={listItemContext}>
+      <ListItemElement
+        className={clsx(
+          'wds-list-item',
+          `wds-list-item-${controlType}`,
+          getFeatureClassName(),
+          {
+            'wds-list-item-interactive': isFullyInteractive,
+            'wds-list-item-partially-interactive': isPartiallyInteractive,
+            [`wds-list-item-spotlight wds-list-item-spotlight-${spotlight}`]:
+              isFullyInteractive && !!spotlight,
+            disabled,
+          },
+          className,
+        )}
+        id={id}
+        aria-disabled={disabled}
+      >
+        {spotlight === 'inactive' && (
+          <svg aria-hidden="true" className="wds-list-item-spotlight__border">
+            <rect />
+          </svg>
+        )}
+
+        <View
+          {...{
+            isPartiallyInteractive,
+            subtitle,
+            additionalInfo,
+            disabled,
+            prompt,
+            controlType,
+            controlProps,
+          }}
+          className={getFeatureClassName()}
+        >
+          {media && <div className="wds-list-item-media">{media}</div>}
+
+          {/* Title + Subtitle + Values - Group */}
+          <div
+            className="wds-list-item-body"
+            style={valueColumnWidth ? gridColumnsStyle : undefined}
+          >
+            {/* Title + Subtitle + Values - Group */}
+            <span
+              className={clsx({
+                'wds-list-item-body-center': title && !subtitle,
+              })}
+            >
+              {(() => {
+                const titles = [
+                  <Body
+                    key={ids.title}
+                    id={ids.title}
+                    type={Typography.BODY_LARGE_BOLD}
+                    className="wds-list-item-title"
+                  >
+                    {title}
+                  </Body>,
+                ];
+                if (subtitle) {
+                  titles.push(
+                    <Body key={ids.subtitle} id={ids.subtitle} className="wds-list-item-subtitle">
+                      {subtitle}
+                    </Body>,
+                  );
+                }
+                return inverted ? [...titles].reverse() : titles;
+              })()}
+            </span>
+
+            {(valueTitle || valueSubtitle) && (
+              <span
+                className={clsx('wds-list-item-value', {
+                  'flex-column': valueTitle !== undefined || valueSubtitle !== undefined,
+                  'wds-list-item-body-center':
+                    (valueTitle && !valueSubtitle) || (!valueTitle && valueSubtitle),
+                })}
+              >
+                {(() => {
+                  const values = [];
+                  if (valueTitle) {
+                    values.push(
+                      <Body
+                        key={ids.valueTitle}
+                        id={ids.valueTitle}
+                        type={Typography.BODY_LARGE_BOLD}
+                        className="wds-list-item-title-value"
+                      >
+                        {valueTitle}
+                      </Body>,
+                    );
+                  }
+                  if (valueSubtitle) {
+                    values.push(
+                      <Body
+                        key={ids.valueSubtitle}
+                        id={ids.valueSubtitle}
+                        className="wds-list-item-subtitle-value"
+                      >
+                        {valueSubtitle}
+                      </Body>,
+                    );
+                  }
+                  return inverted ? [...values].reverse() : values;
+                })()}
+              </span>
+            )}
+          </div>
+
+          {control === null ? null : (
+            <Body
+              className={clsx('wds-list-item-control-wrapper', {
+                'wds-list-item-button-control': controlType === 'button',
+              })}
+              style={
+                {
+                  '--wds-list-item-control-wrapper-height': mediaSize ? `${mediaSize}px` : 'auto',
+                } as React.CSSProperties
+              }
+            >
+              {control}
+            </Body>
+          )}
+        </View>
+      </ListItemElement>
+    </ListItemContext.Provider>
+  );
+};
+
+type ViewProps = PropsWithChildren<{
+  isPartiallyInteractive: boolean;
+  controlType?: ListItemTypes;
+  controlProps?: ListItemControlProps;
+}> &
+  Pick<ListItemProps, 'subtitle' | 'additionalInfo' | 'disabled' | 'prompt' | 'className'>;
+
+function View({
+  children,
+  subtitle,
+  additionalInfo,
+  prompt,
+  disabled,
+  isPartiallyInteractive,
+  controlType = 'non-interactive',
+  controlProps,
+  className = '',
+}: ViewProps) {
+  const { ids, describedByIds } = useContext<ListItemContextData>(ListItemContext);
+  const isLinkControl = ['navigation'].includes(controlType);
+
+  const isHrefProvided = isLinkControl && !!(controlProps as ListItemNavigationProps)?.href;
+
+  const renderExtras = () => (
+    <>
+      {additionalInfo}
+      {prompt}
+    </>
+  );
+
+  if (isLinkControl && isHrefProvided) {
+    return (
+      // for link instances of .Navigation, .IconButton, .Button
+      <div className={clsx('wds-list-item-gridWrapper', className)}>
+        <PrimitiveAnchor
+          aria-describedby={describedByIds}
+          href={(controlProps as ListItemNavigationProps)?.href}
+          target={(controlProps as ListItemNavigationProps)?.target}
+          className={clsx('wds-list-item-view d-flex flex-row', {
+            'wds-list-item-control': controlType === 'navigation',
+            fullyInteractive: !isPartiallyInteractive,
+          })}
+          disabled={disabled}
+          onClick={(controlProps as PrimitiveAnchorProps | undefined)?.onClick}
+        >
+          {children}
+        </PrimitiveAnchor>
+
+        {renderExtras()}
+      </div>
+    );
+  }
+
+  if (isPartiallyInteractive || controlType === 'non-interactive') {
+    return (
+      <div className={clsx('wds-list-item-gridWrapper', className)}>
+        <div className={clsx('wds-list-item-view d-flex flex-row')}>{children}</div>
+
+        {renderExtras()}
+      </div>
+    );
+  }
+
+  // for form control instances of .Radio, .Checkbox, .Switch, .Button, .Navigation etc
+  // Radio cannot be wrapped in a <fieldset> element to announce it as a group.
+  const InputWrapper = controlType === 'radio' ? 'div' : 'fieldset';
+  return (
+    <InputWrapper className={clsx('wds-list-item-gridWrapper', className)}>
+      <label
+        htmlFor={ids.control}
+        className={clsx('wds-list-item-view', {
+          clickable: !disabled,
+          fullyInteractive: !isPartiallyInteractive,
+        })}
+      >
+        {children}
+      </label>
+
+      {renderExtras()}
+    </InputWrapper>
+  );
+}
+
+ListItem.Image = Image;
+ListItem.AvatarView = AvatarView;
+ListItem.AvatarLayout = AvatarLayout;
+ListItem.AdditionalInfo = AdditionalInfo;
+ListItem.Checkbox = Checkbox;
+ListItem.Radio = Radio;
+ListItem.IconButton = IconButton;
+ListItem.Navigation = Navigation;
+ListItem.Button = Button;
+ListItem.Switch = Switch;
+ListItem.Prompt = Prompt;
+
+export default ListItem;

package/src/listItem/ListItemContext.tsx

@@ -0,0 +1,26 @@
+import { createContext } from 'react';
+import type { ListItemTypes, ListItemControlProps, ListItemProps } from './ListItem';
+
+export type ListItemMediaSize = 32 | 40 | 48 | 56 | 72;
+
+export type ListItemContextData = {
+  setControlType: (type: ListItemTypes) => void;
+  setControlProps: (props: ListItemControlProps) => void;
+  setMediaSize: (size: ListItemMediaSize | undefined) => void;
+  ids: {
+    title: string;
+    subtitle?: string;
+    valueTitle?: string;
+    valueSubtitle?: string;
+    additionalInfo?: string;
+    control: string;
+    prompt?: string;
+  };
+  props: Pick<ListItemProps, 'disabled' | 'inverted'>;
+  mediaSize?: ListItemMediaSize;
+  describedByIds: string;
+};
+
+export const ListItemContext = createContext<ListItemContextData>(
+  null as unknown as ListItemContextData,
+);

package/src/listItem/Navigation/ListItemNavigation.spec.tsx

@@ -0,0 +1,67 @@
+import { render, screen } from '../../test-utils';
+import userEvent from '@testing-library/user-event';
+import { ListItem, type ListItemProps } from '../ListItem';
+
+describe('ListItem.Navigation', () => {
+  const renderWith = (overrides: Partial<ListItemProps> = {}) =>
+    render(<ListItem title="Test Title" {...overrides} />);
+
+  describe('as button', () => {
+    it('renders as button if onClick is set but no href', () => {
+      renderWith({ control: <ListItem.Navigation onClick={() => {}} /> });
+      expect(screen.getByRole('button')).toBeInTheDocument();
+    });
+
+    it('handles onClick events', async () => {
+      const handleClick = jest.fn();
+      renderWith({ control: <ListItem.Navigation onClick={handleClick} /> });
+
+      await userEvent.click(screen.getByRole('button'));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('respects disabled state', async () => {
+      renderWith({
+        disabled: true,
+        control: <ListItem.Navigation onClick={jest.fn()} />,
+      });
+      expect(screen.getByTestId('backslash-circle-icon')).toBeInTheDocument();
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('as link', () => {
+    it('renders a link if href is set', () => {
+      renderWith({ control: <ListItem.Navigation href="/test-path" /> });
+
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+      expect(screen.getByRole('link')).toBeInTheDocument();
+    });
+
+    it('respects target prop', () => {
+      renderWith({
+        control: <ListItem.Navigation href="/test-path" target="_blank" />,
+      });
+      const link = screen.getByRole('link');
+      expect(link).toHaveAttribute('target', '_blank');
+      expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+    });
+
+    it('renders disabled icon when ListItem is disabled', () => {
+      renderWith({
+        disabled: true,
+        control: <ListItem.Navigation href="wise.com" />,
+      });
+      expect(screen.getByTestId('backslash-circle-icon')).toBeInTheDocument();
+    });
+
+    it('handles onClick events', async () => {
+      const handleClick = jest.fn();
+      renderWith({ control: <ListItem.Navigation href="#target" onClick={handleClick} /> });
+
+      await userEvent.click(screen.getByRole('link'));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/listItem/Navigation/ListItemNavigation.story.tsx

@@ -0,0 +1,114 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { fn } from 'storybook/test';
+import { lorem10 } from '../../test-utils';
+import List from '../../list';
+import { ListItem } from '../ListItem';
+import {
+  SB_LIST_ITEM_ADDITIONAL_INFO as INFO,
+  SB_LIST_ITEM_PROMPTS as PROMPTS,
+  SB_LIST_ITEM_MEDIA as MEDIA,
+} from '../_stories/subcomponents';
+import type { ListItemNavigationProps } from './ListItemNavigation';
+
+const meta: Meta<ListItemNavigationProps> = {
+  component: ListItem.Navigation,
+  title: 'Content/ListItem/ListItem.Navigation',
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
+  args: {
+    href: 'https://wise.com',
+    onClick: fn(),
+    target: undefined,
+  },
+  argTypes: {
+    onClick: {
+      description:
+        'If `href` is falsy and `onClick` is set, the component will render as an HTML button.',
+    },
+    target: {
+      control: 'select',
+      options: [undefined, '_blank', '_self', '_parent', '_top'],
+      description:
+        'The `target` attribute for HTML anchor. If set to `_blank`, `rel="noopener noreferrer"` is automatically added to the rendered node.',
+    },
+  },
+} satisfies Meta<ListItemNavigationProps>;
+
+export default meta;
+
+type Story = StoryObj<ListItemNavigationProps>;
+
+export const Playground: Story = {
+  tags: ['!autodocs'],
+  render: (args: ListItemNavigationProps) => {
+    return (
+      <List>
+        <ListItem
+          title="List item title"
+          subtitle="Subtitle goes here"
+          media={MEDIA.avatarSingle}
+          control={<ListItem.Navigation {...args} />}
+          additionalInfo={INFO.nonInteractive}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * Navigation control can be rendered as HTML anchor or a button
+ */
+export const AsButton: Story = {
+  args: {
+    onClick: fn(),
+  },
+  parameters: {
+    controls: { disable: true },
+  },
+  render: (args) => {
+    return (
+      <List>
+        <ListItem
+          control={
+            <ListItem.Navigation href="https://wise.com" target="_blank" onClick={args.onClick} />
+          }
+          title="Navigation as link"
+          subtitle="This will navigate to an external URL"
+          media={MEDIA.avatarSingle}
+        />
+
+        <ListItem
+          control={<ListItem.Navigation onClick={args.onClick} />}
+          title="Navigation as button"
+          subtitle="This will trigger a click handler"
+          media={MEDIA.avatarSingle}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * Unlike other controls, the Navigation control has a custom disabled state
+ * for improved discoverability, accessibility and overall UX.
+ */
+export const Disabled: Story = {
+  render: (args) => {
+    return (
+      <List>
+        <ListItem
+          disabled
+          control={<ListItem.Navigation {...args} />}
+          title="This option is disabled"
+          subtitle={lorem10}
+          additionalInfo={INFO.nonInteractive}
+          prompt={PROMPTS.interactive}
+          media={MEDIA.avatarSingle}
+        />
+      </List>
+    );
+  },
+};

package/src/listItem/Navigation/ListItemNavigation.tsx

@@ -0,0 +1,39 @@
+import { ChevronRight, BackslashCircle } from '@transferwise/icons';
+import type { ButtonProps } from '../../button/Button.types';
+import { useListItemControl } from '../useListItemControl';
+import { PrimitiveButton } from '../../primitives';
+import { useContext } from 'react';
+import { ListItemContext } from '../ListItemContext';
+
+export type ListItemNavigationProps = Pick<ButtonProps, 'onClick' | 'href' | 'target'>;
+
+/**
+ * This component allows for rendering a control functionally synonymous with HTML `anchor` or a
+ * `button`, giving users a rich way to choose between options and navigate to another screen or
+ * step in a flow. It offers only a subset of features of the HTML element in line with the
+ * ListItem's constraints.<br />
+ * <br />
+ * Please refer to the [Design documentation](https://wise.design/components/list-item---navigation) for details.
+ */
+export const Navigation = function Navigation({ href, ...props }: ListItemNavigationProps) {
+  const { baseItemProps } = useListItemControl('navigation', { href, ...props });
+  const { ids, describedByIds } = useContext(ListItemContext);
+  const icon = <ChevronRight size={16} />;
+
+  if (baseItemProps.disabled) return <BackslashCircle size={24} />;
+
+  return href ? (
+    <>{icon}</>
+  ) : (
+    <PrimitiveButton
+      aria-describedby={describedByIds}
+      id={ids.control}
+      className="btn-unstyled wds-list-item-control"
+      onClick={props.onClick as React.MouseEventHandler<HTMLButtonElement> | undefined}
+    >
+      {icon}
+    </PrimitiveButton>
+  );
+};
+
+Navigation.displayName = 'ListItem.Navigation';

package/src/listItem/Navigation/index.ts

@@ -0,0 +1,2 @@
+export type { ListItemNavigationProps } from './ListItemNavigation';
+export { Navigation } from './ListItemNavigation';