@transferwise/components 45.12.0 → 45.13.0

package/src/promoCard/PromoCard.story.tsx

@@ -0,0 +1,90 @@
+import { Meta, StoryObj } from '@storybook/react';
+
+import PromoCard from './PromoCard';
+
+const meta: Meta<typeof PromoCard> = {
+  component: PromoCard,
+  title: 'Layouts/PromoCard',
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof PromoCard>;
+
+export const Default: Story = {
+  args: {
+    description: 'A card that lives online and works anywhere. Easy, secure, and always on hand.',
+    title: 'Digital',
+    indicatorLabel: 'Free',
+    imageSource: 'https://wise.com/web-art/assets/illustrations/digital-card-2-medium@2x.webp',
+  },
+};
+
+export const Link: Story = {
+  args: {
+    description: 'A card that lives online and works anywhere. Easy, secure, and always on hand.',
+    title: 'Digital',
+    href: 'https://wise.com',
+    indicatorLabel: 'Free',
+    imageSource: 'https://wise.com/web-art/assets/illustrations/digital-card-2-medium@2x.webp',
+  },
+};
+
+export const Check: Story = {
+  args: {
+    description: 'A card that lives online and works anywhere. Easy, secure, and always on hand.',
+    title: 'Digital',
+    type: 'checkbox',
+    indicatorLabel: 'Free',
+    imageSource: 'https://wise.com/web-art/assets/illustrations/digital-card-2-medium@2x.webp',
+  },
+};
+
+export const DefaultChecked: Story = {
+  args: {
+    description: 'A card that lives online and works anywhere. Easy, secure, and always on hand.',
+    title: 'Digital',
+    type: 'checkbox',
+    indicatorLabel: 'Free',
+    defaultChecked: true,
+    imageSource: 'https://wise.com/web-art/assets/illustrations/digital-card-2-medium@2x.webp',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    description: 'A card that lives online and works anywhere. Easy, secure, and always on hand.',
+    title: 'Digital',
+    type: 'checkbox',
+    isDisabled: true,
+    indicatorLabel: 'Free',
+    imageSource: 'https://wise.com/web-art/assets/illustrations/digital-card-2-medium@2x.webp',
+  },
+};
+
+export const CustomClass: Story = {
+  args: {
+    description: 'A card that lives online and works anywhere. Easy, secure, and always on hand.',
+    title: 'Digital',
+    href: 'https://wise.com',
+    className: 'np-CustomPromoCard',
+    indicatorLabel: 'Free',
+    imageSource: 'https://wise.com/web-art/assets/illustrations/digital-card-medium@2x.webp',
+  },
+  decorators: [
+    (Story) => (
+      <div>
+        <style>
+          {`
+          .np-CustomPromoCard {
+            --Card-background-color: var(--color-bright-yellow);
+            --Card-indicator-icon-background-color: var(--color-dark-gold);
+            --Card-indicator-icon-color: var(--color-contrast);
+          }
+        `}
+        </style>
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/promoCard/PromoCard.tsx

@@ -0,0 +1,343 @@
+import { Check } from '@transferwise/icons';
+import classNames from 'classnames';
+import React, { forwardRef, FunctionComponent, useState, useEffect, useMemo } from 'react';
+
+import Body from '../body';
+import { Typography } from '../common';
+import Card from '../common/card';
+import Display from '../display';
+import Image from '../image/Image';
+
+import { usePromoCardContext } from './PromoCardContext';
+import PromoCardIndicator from './PromoCardIndicator';
+
+export type ReferenceType = React.Ref<HTMLInputElement>;
+export type LinkTarget = '_blank' | '_parent' | '_self' | '_top';
+export type RelatedTypes =
+  | ''
+  | 'alternate'
+  | 'author'
+  | 'bookmark'
+  | 'external'
+  | 'help'
+  | 'license'
+  | 'next'
+  | 'nofollow'
+  | 'noreferrer'
+  | 'noopener'
+  | 'prev'
+  | 'search'
+  | 'tag';
+
+export interface PromoCardCommonProps {
+  /** Optional prop to specify classNames onto the PromoCard */
+  className?: string;
+
+  /** Optional prop to specify the ID of the PromoCard */
+  id?: string;
+
+  /** Required prop to specify the descriptive text of the PromoCard  */
+  description: string;
+
+  /**
+   * Optional prop to specify the heading level of the PromoCard
+   *
+   * @default 'h3'
+   */
+  headingLevel?: 'h3' | 'h4' | 'h5' | 'h6';
+
+  /** Optional prop to specify text for the indicator label of the PromoCard */
+  indicatorLabel?: string;
+
+  /** Optional prop to specify an image alt text  */
+  imageAlt?: string;
+
+  /** Optional prop to specify an image class  */
+  imageClass?: string;
+
+  /** Optional prop to specify an image source url  */
+  imageSource: string;
+
+  /** Specify whether the PromoCard is disabled, or not */
+  isDisabled?: boolean;
+
+  /** Specify an onClick event handler */
+  onClick?: () => void;
+
+  /** Optional prop to specify the ID used for testing */
+  testId?: string;
+
+  /** Required prop to specify the title text of the PromoCard  */
+  title: string;
+}
+
+export interface PromoCardLinkProps extends PromoCardCommonProps {
+  /**
+   * Optional prop to prompts a user to save the linked URL instead of
+   * navigating to it
+   */
+  download?: string;
+
+  /** Optionally specify an href for your PromoCard to contain an <a> element */
+  href?: string;
+
+  /** Optionally specify the language of the linked URL */
+  hrefLang?: string;
+
+  /**
+   * Relationship between the PromoCard href URL and the current page. See
+   * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel).
+   */
+  rel?: RelatedTypes;
+
+  /** Optional prop to to display where the linked URL will show */
+  target?: LinkTarget;
+
+  /** Only applies to role="radio" or "checkbox" */
+  defaultChecked?: never;
+  isChecked?: never;
+  tabIndex?: never;
+  type?: never;
+  reference?: never;
+  value?: never;
+}
+
+export interface PromoCardCheckedProps extends PromoCardCommonProps {
+  /** Specify the initial checked attribute of the PromoCard */
+  defaultChecked?: boolean;
+
+  /** Specify whether the PromoCard is checked, or not */
+  isChecked?: boolean;
+
+  /** Optional prop to specify the tabIndex of the PromoCard */
+  tabIndex?: number;
+
+  /** Optional property to provide component Ref */
+  reference?: ReferenceType;
+
+  /** Optional prop to specify the input type of the PromoCard  */
+  type?: 'checkbox' | 'radio';
+
+  /** Specify the value attribute of the PromoCard if Checkbox or Radio */
+  value?: string;
+
+  /** Only applies to <a />s */
+  download?: never;
+  href?: never;
+  hrefLang?: never;
+  rel?: never;
+  target?: never;
+}
+
+export type PromoCardProps = PromoCardLinkProps | PromoCardCheckedProps;
+
+export type PolymorphicPromoCard = (
+  props: PromoCardLinkProps | PromoCardCheckedProps,
+) => JSX.Element;
+
+/**
+ * generateRandomId() function
+ *
+ * This function generates a random string of characters that can be used as
+ * an ID.
+ *
+ * @returns {string} A random string of characters.
+ * @example
+ * const id = generateRandomId();
+ * // id will be a random string of characters, such as "id-4711".
+ */
+const generateRandomId = (): string => {
+  return `id-${Math.random().toString(36).slice(7)}`;
+};
+
+/**
+ * PromoCard component.
+ *
+ * PromoCard is a marketing style component that is used to group marketing
+ * product related information (such as choosing Card types). It can be used to
+ * display information in a structured way, and can be customized with various
+ * props to suit different use cases.
+ *
+ * @component
+ * @param {string} className - Additional class name for the PromoCard.
+ * @param {string} description - Description text for the PromoCard.
+ * @param {boolean} defaultChecked - Initial checked state for checkboxes and radios.
+ * @param {string} download - Download file name for links.
+ * @param {string} href - URL for links.
+ * @param {string} hrefLang - Language code for linked URL.
+ * @param {string} id - ID of the PromoCard.
+ * @param {string} imageAlt - Alt text for the image.
+ * @param {string} imageSource - Source URL of the image.
+ * @param {string} indicatorLabel - Label for the indicator icon.
+ * @param {boolean} isChecked - Checked state for checkboxes and radios.
+ * @param {boolean} isDisabled - Whether the PromoCard is disabled.
+ * @param {Function} onClick - Click event handler for the PromoCard.
+ * @param {string} rel - Relationship between the URL and the current page.
+ * @param {number} tabIndex - Tab index for keyboard navigation.
+ * @param {string} target - Target window for links.
+ * @param {string} testId - ID used for testing.
+ * @param {string} title - Title text of the PromoCard.
+ * @param {('checkbox'|'radio')} type - Type of the PromoCard (checkbox, radio).
+ * @param {string} value - Value for checkboxes and radios.
+ * @returns {JSX.Element} The rendered PromoCard component.
+ * @example
+ * <PromoCard
+ *   title="Example PromoCard"
+ *   description="This is an example PromoCard with a link variation."
+ *   href="https://example.com"
+ *   target="_blank"
+ *   imageSource="https://example.com/image.png"
+ *   imageAlt="Example Image"
+ *   indicatorLabel="Learn More"
+ * />
+ */
+const PromoCard: FunctionComponent<PromoCardProps> = forwardRef(
+  (
+    {
+      className,
+      description,
+      defaultChecked,
+      download,
+      href,
+      hrefLang,
+      id,
+      headingLevel = 'h3',
+      imageAlt,
+      imageClass,
+      imageSource,
+      indicatorLabel,
+      isChecked,
+      isDisabled,
+      onClick,
+      rel,
+      tabIndex,
+      target,
+      testId,
+      title,
+      type,
+      value,
+      ...props
+    },
+    reference,
+  ) => {
+    // Set the `checked` state to the value of `defaultChecked` if it is truthy,
+    // or the value of `isChecked` if it is truthy, or `false` if neither
+    // is truthy.
+    const { state, onChange, isDisabled: contextIsDisabled } = usePromoCardContext();
+    const [checked, setChecked] = useState(
+      type === 'checkbox' ? defaultChecked ?? isChecked ?? false : false,
+    );
+
+    const handleClick = () => {
+      if (type === 'radio') {
+        onChange(value || ''); // Update the context state for radio
+      } else if (type === 'checkbox') {
+        setChecked(!checked); // Update local state for checkbox
+      }
+    };
+
+    const componentId = `${id || generateRandomId()}`;
+
+    // Set the icon to `'arrow'` if `href` is truthy and `type` is falsy, or
+    // `'download'` if `download` is truthy. If neither condition is true, set
+    // `icon` to `undefined`.
+    const icon = href && download ? 'download' : href ? 'arrow' : undefined;
+
+    // Define all class names string based on the values of the `href`, `type`,
+    // `checked`, and `className` props.
+    const commonClasses = classNames({
+      'np-Card--promoCard': true,
+      'np-Card--checked': !href && type,
+      'np-Card--link': href && !type,
+      'is-checked': type === 'radio' ? value === state : type === 'checkbox' ? checked : undefined,
+      [`${className || ''}`]: className,
+    });
+
+    // Object with common props that will be passed to the `Card` components
+    const commonProps = {
+      className: commonClasses,
+      id: componentId,
+      isDisabled: isDisabled || contextIsDisabled,
+      onClick,
+      ref: reference,
+      'data-testid': testId,
+    };
+
+    // Object with Anchor props that will be passed to the `a` element. These
+    // won't be refurned if set to `isDisabled`
+    const anchorProps =
+      href && !isDisabled
+        ? {
+            download,
+            href: href || undefined,
+            hrefLang,
+            rel,
+            target,
+          }
+        : {};
+
+    // Object of all Checked props that will be passed to the root `Card` component
+    const checkedProps =
+      (type === 'checkbox' || type === 'radio') && !href
+        ? {
+            ...commonProps,
+            'aria-checked':
+              type === 'radio' ? value === state : type === 'checkbox' ? checked : undefined,
+            'aria-describedby': `${componentId}-title` || undefined,
+            'aria-disabled': isDisabled,
+            'data-value': value ?? undefined,
+            role: type === 'checkbox' || type === 'radio' ? type : undefined,
+            onClick: handleClick,
+            onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => {
+              if (event.key === 'Enter' || event.key === ' ') {
+                handleClick();
+              }
+            },
+            ref: reference,
+            tabIndex: 0,
+          }
+        : {};
+
+    useEffect(() => {
+      setChecked(defaultChecked ?? isChecked ?? false);
+    }, [defaultChecked, isChecked]);
+
+    return (
+      <Card {...commonProps} {...checkedProps} {...props}>
+        {(value === state || checked) && (
+          <span className="np-Card-check">
+            <Check size={24} aria-hidden="true" />
+          </span>
+        )}
+        <Display
+          id={`${componentId}-title`}
+          as={headingLevel}
+          className="np-Card-title"
+          type={Typography.DISPLAY_SMALL}
+        >
+          {href && !type ? (
+            <a className="np-Card-titleLink" {...anchorProps}>
+              {title}
+            </a>
+          ) : (
+            title
+          )}
+        </Display>
+        <Body className="np-Card-description">{description}</Body>
+        {imageSource && (
+          <div className={classNames('np-Card-image', { imageClass })}>
+            <Image
+              src={imageSource}
+              alt={imageAlt}
+              role={!imageAlt ? 'presentation' : null}
+              loading="lazy"
+            />
+          </div>
+        )}
+        <PromoCardIndicator label={indicatorLabel} icon={icon} />
+      </Card>
+    );
+  },
+) as PolymorphicPromoCard;
+
+export default React.memo(PromoCard);

package/src/promoCard/PromoCardContext.spec.tsx

@@ -0,0 +1,52 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+
+import { PromoCardContext, usePromoCardContext } from './PromoCardContext';
+
+// A simple component that consumes the context
+const TestComponent: React.FC = () => {
+  const context = usePromoCardContext();
+
+  return (
+    <div>
+      <p>{`Value: ${context.state}`}</p>
+      <p>{`Disabled: ${context.isDisabled.toString()}`}</p>
+    </div>
+  );
+};
+
+describe('PromoCardContext', () => {
+  it('default values are accessible', () => {
+    const contextValue = {
+      state: '',
+      isDisabled: false,
+      onChange: jest.fn(), // You can mock this function for testing
+    };
+
+    render(
+      <PromoCardContext.Provider value={contextValue}>
+        <TestComponent />
+      </PromoCardContext.Provider>,
+    );
+
+    expect(screen.getByText('Value:')).toBeInTheDocument();
+    expect(screen.getByText('Disabled: false')).toBeInTheDocument();
+  });
+
+  it('context value changes are reflected', () => {
+    const contextValue = {
+      state: 'new value',
+      isDisabled: true,
+      onChange: jest.fn(), // You can mock this function for testing
+    };
+
+    render(
+      <PromoCardContext.Provider value={contextValue}>
+        <TestComponent />
+      </PromoCardContext.Provider>,
+    );
+
+    expect(screen.getByText('Value: new value')).toBeInTheDocument();
+    expect(screen.getByText('Disabled: true')).toBeInTheDocument();
+  });
+});

package/src/promoCard/PromoCardContext.tsx

@@ -0,0 +1,58 @@
+import React, { useContext, createContext } from 'react';
+
+/**
+ * The type of the PromoCard context object.
+ *
+ * The context object contains the current state of the PromoCard group, whether
+ * the group is disabled or not, and a function to call when the group value
+ * changes. This value is used to provide context to child PromoCard components,
+ * allowing them to interact with the group and update its state.
+ */
+interface PromoCardContextType {
+  /**
+   * The current value of the PromoCard group.
+   *
+   * @default ''
+   */
+  state: string;
+  /**
+   * Whether the PromoCard group is disabled or not.
+   *
+   * @default false
+   */
+  isDisabled: boolean;
+  /**
+   * A function to call when the PromoCard group value changes.
+   *
+   * @param {string} value - The new value of the PromoCard group.
+   * @default () => {}
+   */
+  onChange: (value: string) => void;
+}
+
+const defaultPromoCardContext: PromoCardContextType = {
+  state: '',
+  isDisabled: false,
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  onChange: () => {},
+};
+
+/**
+ * The PromoCard context object.
+ */
+export const PromoCardContext = createContext<PromoCardContextType>(defaultPromoCardContext);
+
+/**
+ * A custom hook for accessing the PromoCard context object.
+ *
+ * The `usePromoCardContext` hook is used to access the PromoCard context object
+ * from within a child PromoCard component. It throws an error if the context
+ * object is not available, which can help with debugging and development.
+ *
+ * @returns {PromoCardContextType} - The PromoCard context object.
+ */
+export const usePromoCardContext = (): PromoCardContextType => {
+  return useContext(PromoCardContext);
+};
+
+export default PromoCardContext;

package/src/promoCard/PromoCardGroup.spec.tsx

@@ -0,0 +1,138 @@
+import { render, screen } from '@testing-library/react';
+
+import PromoCard, { PromoCardProps } from './PromoCard';
+import PromoCardGroup, { PromoCardGroupProps } from './PromoCardGroup';
+
+describe('PromoCardGroup', () => {
+  const defaultCardProps: PromoCardProps = {
+    title: 'Test Card',
+    description: 'Test Description',
+    imageSource: 'https://via.placeholder.com/150',
+    type: 'radio',
+  };
+
+  const defaultProps = {
+    testId: 'test-promo-card-group',
+    children: [
+      <PromoCard
+        key="radio-1"
+        {...defaultCardProps}
+        testId="test-1"
+        value="radio-1"
+        id="radio-1"
+      />,
+      <PromoCard
+        key="radio-2"
+        {...defaultCardProps}
+        testId="test-2"
+        value="radio-2"
+        id="radio-2"
+      />,
+    ],
+  };
+
+  let rerenderPromoCardGroup: (props?: PromoCardGroupProps) => void;
+
+  beforeEach(() => {
+    const { rerender } = render(<PromoCardGroup {...defaultProps} />);
+
+    rerenderPromoCardGroup = (props?: PromoCardGroupProps) => {
+      rerender(<PromoCardGroup {...defaultProps} {...props} />);
+    };
+  });
+
+  it('matches snapshot', () => {
+    const { container } = render(<PromoCardGroup {...defaultProps} />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('renders', () => {
+    const props = {
+      ...defaultProps,
+      children: [
+        <PromoCard
+          key="radio-3"
+          {...defaultCardProps}
+          type="checkbox"
+          testId="test-3"
+          value="radio-3"
+        />,
+        <PromoCard
+          key="radio-4"
+          {...defaultCardProps}
+          type="checkbox"
+          testId="test-4"
+          value="radio-4"
+        />,
+      ],
+    };
+    expect(screen.getByTestId('test-promo-card-group')).toBeInTheDocument();
+    expect(screen.getByTestId('test-promo-card-group')).toHaveClass('np-CardGroup');
+    expect(screen.getByRole('radiogroup')).toBeInTheDocument();
+
+    // Change children
+    rerenderPromoCardGroup(props);
+
+    expect(screen.getByTestId('test-4')).toBeInTheDocument();
+  });
+
+  it('sets the `defaultValue` for the group', () => {
+    const props = {
+      ...defaultProps,
+      defaultChecked: 'radio-1',
+    };
+
+    expect(screen.getByTestId('test-1')).not.toHaveClass('is-checked');
+
+    // Change children
+    rerenderPromoCardGroup(props);
+
+    expect(screen.getByTestId('test-1')).toHaveClass('is-checked');
+  });
+
+  it('not to render as a `radiogroup` if we have a mix of PromoCard types', () => {
+    const props = {
+      ...defaultProps,
+      children: [
+        <PromoCard
+          key="radio-3"
+          {...defaultCardProps}
+          type="checkbox"
+          testId="test-3"
+          value="radio-3"
+        />,
+        <PromoCard
+          key="radio-4"
+          {...defaultCardProps}
+          type="checkbox"
+          testId="test-4 "
+          value="radio-4"
+        />,
+      ],
+    };
+
+    expect(screen.getByRole('radiogroup')).toBeInTheDocument();
+
+    // Change children
+    rerenderPromoCardGroup(props);
+
+    expect(screen.queryByRole('radiogroup')).not.toBeInTheDocument();
+    expect(screen.getByTestId('test-4')).toBeInTheDocument();
+  });
+
+  it('applies `is-disabled` class to all children when isDisabled is true', () => {
+    const props = {
+      ...defaultProps,
+      isDisabled: true,
+    };
+
+    expect(screen.getByTestId('test-1')).not.toHaveClass('is-disabled');
+    expect(screen.getByTestId('test-2')).not.toHaveClass('is-disabled');
+
+    // Change children
+    rerenderPromoCardGroup(props);
+
+    expect(screen.getByTestId('test-1')).toHaveClass('is-disabled');
+    expect(screen.getByTestId('test-2')).toHaveClass('is-disabled');
+  });
+});