@transferwise/components 46.166.0 → 46.167.0

package/src/CardWidget/CardWidget.test.tsx

@@ -0,0 +1,221 @@
+import { Plus, Settings } from '@transferwise/icons';
+
+import { mockMatchMedia, render, screen, userEvent } from '../test-utils';
+import CardWidget from './CardWidget';
+import type { CardWidgetHeader } from './CardWidget.types';
+
+mockMatchMedia();
+
+describe('CardWidget', () => {
+  const content = 'Widget content';
+
+  const renderWidget = (header: Partial<CardWidgetHeader> = {}) =>
+    render(
+      <CardWidget data-testid="widget" header={{ title: 'Cards', ...header }}>
+        {content}
+      </CardWidget>,
+    );
+
+  describe('rendering', () => {
+    it('renders children without a header', () => {
+      render(<CardWidget data-testid="widget">{content}</CardWidget>);
+      expect(screen.getByText(content)).toBeInTheDocument();
+      expect(screen.queryByRole('heading')).not.toBeInTheDocument();
+      expect(screen.getByTestId('widget')).not.toHaveClass('wds-card-widget--with-header');
+    });
+
+    it('renders on a CardContainer', () => {
+      render(
+        <CardWidget data-testid="widget" spotlight="active" as="article" className="custom">
+          {content}
+        </CardWidget>,
+      );
+      const root = screen.getByTestId('widget');
+      expect(root.tagName).toBe('ARTICLE');
+      expect(root).toHaveClass(
+        'wds-card-container',
+        'wds-card-container--active',
+        'wds-card-widget',
+        'custom',
+      );
+    });
+
+    it('always keeps the default padding', () => {
+      // `padding` is not a CardWidget prop, but untyped consumers can still pass it.
+      const untypedProps = { padding: 'none' } as object;
+      render(
+        <CardWidget data-testid="widget" {...untypedProps}>
+          {content}
+        </CardWidget>,
+      );
+      expect(screen.getByTestId('widget')).not.toHaveClass('wds-card-container--padding-none');
+    });
+
+    it('renders the title as an h3 by default', () => {
+      renderWidget();
+      expect(screen.getByRole('heading', { level: 3, name: 'Cards' })).toBeInTheDocument();
+      expect(screen.getByTestId('widget')).toHaveClass('wds-card-widget--with-header');
+    });
+
+    it('renders the title as the given heading level', () => {
+      renderWidget({ as: 'h2' });
+      expect(screen.getByRole('heading', { level: 2, name: 'Cards' })).toBeInTheDocument();
+    });
+
+    it('renders the header without content', () => {
+      render(<CardWidget header={{ title: 'Cards' }} />);
+      expect(screen.getByRole('heading', { name: 'Cards' })).toBeInTheDocument();
+      expect(document.querySelector('.wds-card-widget__content')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('titleAction', () => {
+    it('renders the title as a link inside the heading', () => {
+      renderWidget({ titleAction: { href: '/cards' } });
+      const link = screen.getByRole('link', { name: 'Cards' });
+      expect(link).toHaveAttribute('href', '/cards');
+      expect(screen.getByRole('heading', { level: 3 })).toContainElement(link);
+    });
+
+    it('calls the titleAction onClick handler', async () => {
+      const onClick = jest.fn();
+      renderWidget({ titleAction: { href: '#cards', onClick } });
+      await userEvent.click(screen.getByRole('link', { name: 'Cards' }));
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('renders the title as a button when titleAction has only onClick', async () => {
+      const onClick = jest.fn();
+      renderWidget({ titleAction: { onClick } });
+      await userEvent.click(screen.getByRole('button', { name: 'Cards' }));
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('marks a title link that opens in a new tab', () => {
+      renderWidget({ titleAction: { href: '/cards', target: '_blank' } });
+      expect(screen.getByRole('link', { name: /Cards/u })).toHaveAttribute('rel', 'noreferrer');
+    });
+
+    it('keeps the title link alongside actions', () => {
+      renderWidget({ titleAction: { href: '/cards' }, action: { label: 'Order card' } });
+      expect(screen.getByRole('link', { name: 'Cards' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Order card' })).toBeInTheDocument();
+    });
+  });
+
+  describe('states', () => {
+    it("always follows the title link, instead of the CardContainer's own states", () => {
+      // `interactive` is not a CardWidget prop, but untyped consumers can still pass it.
+      const untypedProps = { interactive: true } as object;
+      render(
+        <CardWidget
+          data-testid="widget"
+          header={{ title: 'Cards', titleAction: { href: '/cards' } }}
+          {...untypedProps}
+        >
+          {content}
+        </CardWidget>,
+      );
+      const root = screen.getByTestId('widget');
+      expect(root).not.toHaveClass('wds-card-container--interactive');
+      expect(root).not.toHaveAttribute('interactive');
+    });
+  });
+
+  describe('actions', () => {
+    it('renders a labelled action as a button', () => {
+      renderWidget({ action: { label: 'Order card' } });
+      expect(screen.getByRole('button', { name: 'Order card' })).toBeInTheDocument();
+    });
+
+    it('renders a labelled action with an href as a link', () => {
+      renderWidget({ action: { label: 'Order card', href: '/cards/order' } });
+      expect(screen.getByRole('link', { name: 'Order card' })).toHaveAttribute(
+        'href',
+        '/cards/order',
+      );
+    });
+
+    it('names an unlabelled action from its aria-label', () => {
+      renderWidget({ action: { 'aria-label': 'Card settings', icon: <Settings size={16} /> } });
+      expect(screen.getByRole('button', { name: 'Card settings' })).toBeInTheDocument();
+    });
+
+    it('calls the action onClick handler', async () => {
+      const onClick = jest.fn();
+      renderWidget({ action: { label: 'Order card', onClick } });
+      await userEvent.click(screen.getByRole('button', { name: 'Order card' }));
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not submit a surrounding form', async () => {
+      const onSubmit = jest.fn((event: React.FormEvent) => event.preventDefault());
+      render(
+        <form method="post" onSubmit={onSubmit}>
+          <CardWidget header={{ title: 'Cards', action: { label: 'Order card' } }} />
+        </form>,
+      );
+      const button = screen.getByRole('button', { name: 'Order card' });
+      expect(button).toHaveAttribute('type', 'button');
+      await userEvent.click(button);
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
+    it('does not call onClick when disabled', async () => {
+      const onClick = jest.fn();
+      renderWidget({ action: { label: 'Order card', disabled: true, onClick } });
+      await userEvent.click(screen.getByRole('button', { name: 'Order card' }));
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('renders actionSecondary before action in the DOM', () => {
+      renderWidget({ action: { label: 'Order card' }, actionSecondary: { label: 'Manage' } });
+      const [first, second] = screen.getAllByRole('button');
+      expect(first).toHaveAccessibleName('Manage');
+      expect(second).toHaveAccessibleName('Order card');
+    });
+
+    it('takes button priority from the slot the action is passed to', () => {
+      renderWidget({ action: { label: 'Order card' }, actionSecondary: { label: 'Manage' } });
+      expect(screen.getByRole('button', { name: 'Order card' })).toHaveClass(
+        'wds-Button--secondary',
+      );
+      expect(screen.getByRole('button', { name: 'Manage' })).toHaveClass(
+        'wds-Button--secondary-neutral',
+      );
+    });
+
+    it('takes icon button priority from the slot the action is passed to', () => {
+      renderWidget({
+        action: { 'aria-label': 'Add', icon: <Plus size={16} /> },
+        actionSecondary: { 'aria-label': 'Settings', icon: <Settings size={16} /> },
+      });
+      expect(screen.getByRole('button', { name: 'Add' })).toHaveClass(
+        'np-icon-button-secondary-default',
+      );
+      expect(screen.getByRole('button', { name: 'Settings' })).toHaveClass(
+        'np-icon-button-tertiary-default',
+      );
+    });
+
+    it('keeps the lower emphasis when actionSecondary is used on its own', () => {
+      renderWidget({ actionSecondary: { label: 'Manage' } });
+      expect(screen.getByRole('button', { name: 'Manage' })).toHaveClass(
+        'wds-Button--secondary-neutral',
+      );
+    });
+
+    it('renders an arbitrary node in place of the action buttons', () => {
+      renderWidget({ action: <span>Custom node</span> });
+      expect(screen.getByText('Custom node')).toBeInTheDocument();
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    });
+
+    it('renders an element as given, even when it has a label prop', () => {
+      const CustomAction = ({ label }: { label: string }) => <span>{label}</span>;
+      renderWidget({ action: <CustomAction label="Custom action" /> });
+      expect(screen.getByText('Custom action')).toBeInTheDocument();
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    });
+  });
+});

package/src/CardWidget/CardWidget.tsx

@@ -0,0 +1,78 @@
+import { ChevronEnd } from '@transferwise/icons';
+import { clsx } from 'clsx';
+import { forwardRef } from 'react';
+
+import CardContainer from '../CardContainer';
+import { Typography } from '../common';
+import Link from '../Link';
+import Title from '../Title';
+import type { CardWidgetHeader, CardWidgetProps } from './CardWidget.types';
+import CardWidgetAction, {
+  isCardWidgetActionButton,
+  type CardWidgetActionSlot,
+} from './CardWidgetAction';
+
+const renderAction = (action: CardWidgetHeader['action'], slot: CardWidgetActionSlot) =>
+  isCardWidgetActionButton(action) ? <CardWidgetAction action={action} slot={slot} /> : action;
+
+const CardWidgetHeaderComponent = ({
+  title,
+  as = 'h3',
+  titleAction,
+  action,
+  actionSecondary,
+}: CardWidgetHeader) => (
+  <div className="wds-card-widget__header">
+    <Title as={as} type={Typography.TITLE_GROUP} className="wds-card-widget__title">
+      {titleAction ? (
+        <Link
+          href={titleAction.href}
+          target={titleAction.target}
+          className="wds-card-widget__title-link"
+          onClick={titleAction.onClick}
+        >
+          {title}
+          {/* The word joiner keeps the chevron on the title's last line instead of wrapping alone. */}
+          <span className="wds-card-widget__title-chevron" aria-hidden>
+            {'\u2060'}
+            <ChevronEnd size={16} />
+          </span>
+        </Link>
+      ) : (
+        title
+      )}
+    </Title>
+    {(action || actionSecondary) && (
+      <div className="wds-card-widget__actions">
+        {actionSecondary && renderAction(actionSecondary, 'actionSecondary')}
+        {action && renderAction(action, 'action')}
+      </div>
+    )}
+  </div>
+);
+
+/**
+ * A `CardContainer` with an optional header — a title, a title link and up to two actions — above
+ * its content. The card shows as hovered or pressed while the title link is, and as hovered while
+ * the link has keyboard focus. Hovering or pressing the rest of the card, or its actions, leaves it
+ * at rest.
+ */
+const CardWidget = forwardRef<HTMLElement, CardWidgetProps>(
+  ({ header, children, className, ...props }, ref) => (
+    <CardContainer
+      ref={ref}
+      className={clsx('wds-card-widget', header && 'wds-card-widget--with-header', className)}
+      {...props}
+      // The widget's states follow its title link alone, so the card's own are left off.
+      interactive={false}
+      padding="md"
+    >
+      {header && <CardWidgetHeaderComponent {...header} />}
+      {children != null && <div className="wds-card-widget__content">{children}</div>}
+    </CardContainer>
+  ),
+);
+
+CardWidget.displayName = 'CardWidget';
+
+export default CardWidget;

package/src/CardWidget/CardWidget.types.ts

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+
+import type { Heading } from '../common';
+import type { CardContainerProps } from '../CardContainer';
+import type { LinkProps } from '../Link';
+import type { CardWidgetActionButton } from './CardWidgetAction';
+
+/**
+ * Props passed to the [Link](https://storybook.wise.design/?path=/docs/typography-link--docs)
+ * that the title is rendered as. A trailing chevron is rendered automatically, so do not put one
+ * in `title`.
+ */
+export type CardWidgetTitleAction = Pick<LinkProps, 'href' | 'target' | 'onClick'>;
+
+export interface CardWidgetHeader {
+  /** The widget's title. */
+  title: ReactNode;
+
+  /**
+   * Heading element rendered for the title.
+   * @default 'h3'
+   */
+  as?: Heading;
+
+  /**
+   * Makes the title a link with a trailing chevron.
+   * @default undefined
+   */
+  titleAction?: CardWidgetTitleAction;
+
+  /**
+   * A `CardWidgetActionButton` object (with a `label` or an `icon`) renders a small button,
+   * anchored to the inline end. Any other node is rendered as given.
+   * @default undefined
+   */
+  action?: CardWidgetActionButton | ReactNode;
+
+  /**
+   * Second action, at a lower emphasis, rendered before `action`. Two is the maximum, to keep
+   * the title legible. Takes the same values as `action`, and keeps its lower emphasis when used
+   * on its own.
+   * @default undefined
+   */
+  actionSecondary?: CardWidgetActionButton | ReactNode;
+}
+
+/**
+ * The widget always has the card's default padding, so its header and content line up, and its
+ * states always follow its title link.
+ */
+export interface CardWidgetProps extends Omit<CardContainerProps, 'padding' | 'interactive'> {
+  /**
+   * The widget's header: a title, optionally a link, and up to two actions.
+   * @default undefined
+   */
+  header?: CardWidgetHeader;
+
+  /**
+   * The widget's content, rendered under the header.
+   * @default undefined
+   */
+  children?: ReactNode;
+}

package/src/CardWidget/CardWidgetAction.tsx

@@ -0,0 +1,128 @@
+import { isValidElement, type MouseEventHandler, type ReactNode } from 'react';
+
+import Button from '../Button';
+import type { ButtonPriority, ButtonProps } from '../Button/Button.types';
+import IconButton, { type IconButtonProps } from '../IconButton';
+
+/** The action slot a `CardWidgetActionButton` was passed to, which is what determines its emphasis. */
+export type CardWidgetActionSlot = 'action' | 'actionSecondary';
+
+type CardWidgetActionButtonBase = Pick<ButtonProps, 'href' | 'target' | 'disabled'> & {
+  /**
+   * `HTMLElement` rather than a narrower target, because an action is a `button` or an `a`
+   * depending on whether `href` is set.
+   * @default undefined
+   */
+  onClick?: MouseEventHandler<HTMLElement>;
+
+  /**
+   * Rendered after `label`, or as the only content of an unlabelled action.
+   * Size it yourself — 16px is expected in both cases.
+   * @default undefined
+   */
+  icon?: ReactNode;
+  'data-testid'?: string;
+};
+
+/** An action with a visible label, rendered as a small button. */
+type CardWidgetLabelledActionButton = CardWidgetActionButtonBase & {
+  /** Non-rendering values are excluded, so an unlabelled action has to meet the icon-only rules. */
+  label: Exclude<ButtonProps['children'], null | undefined | boolean>;
+  /** @default undefined */
+  'aria-label'?: string;
+};
+
+/**
+ * An action with no visible label, rendered as a 32px icon button. The icon is
+ * the only thing on screen and `aria-label` is the only accessible name, so
+ * both are required.
+ */
+type CardWidgetIconActionButton = CardWidgetActionButtonBase & {
+  label?: never;
+  icon: ReactNode;
+  'aria-label': string;
+};
+
+/**
+ * An action the `CardWidget` header renders as a button. With a `label` it is a small `Button`; without
+ * one, a 32px `IconButton`, which requires both an `icon` and an `aria-label`. Emphasis is not
+ * part of the object — it comes from the slot the action is passed to.
+ */
+export type CardWidgetActionButton = CardWidgetLabelledActionButton | CardWidgetIconActionButton;
+
+const BUTTON_PRIORITY = {
+  action: 'secondary',
+  actionSecondary: 'secondary-neutral',
+} as const satisfies Record<CardWidgetActionSlot, ButtonPriority>;
+
+const ICON_BUTTON_PRIORITY = {
+  action: 'secondary',
+  actionSecondary: 'tertiary',
+} as const satisfies Record<CardWidgetActionSlot, IconButtonProps['priority']>;
+
+/**
+ * Tells a `CardWidgetActionButton` object apart from any other node passed to an action slot.
+ * Every button action has a `label` or an `icon`, which no React element, portal or array does.
+ */
+export const isCardWidgetActionButton = (value: unknown): value is CardWidgetActionButton =>
+  typeof value === 'object' &&
+  value !== null &&
+  !isValidElement(value) &&
+  !Array.isArray(value) &&
+  ('label' in value || 'icon' in value);
+
+/** Renders a `CardWidgetActionButton` at the emphasis of the slot it was passed to. */
+const CardWidgetAction = function CardWidgetAction({
+  action: {
+    label,
+    icon,
+    'aria-label': ariaLabel,
+    'data-testid': dataTestId,
+    href,
+    target,
+    onClick,
+    disabled,
+  },
+  slot,
+}: {
+  action: CardWidgetActionButton;
+  slot: CardWidgetActionSlot;
+}) {
+  if (label === undefined) {
+    return (
+      <IconButton
+        size={32}
+        priority={ICON_BUTTON_PRIORITY[slot]}
+        aria-label={ariaLabel}
+        href={href}
+        target={target}
+        disabled={disabled}
+        data-testid={dataTestId}
+        onClick={onClick}
+      >
+        {icon}
+      </IconButton>
+    );
+  }
+
+  return (
+    <Button
+      v2
+      size="sm"
+      priority={BUTTON_PRIORITY[slot]}
+      aria-label={ariaLabel}
+      href={href}
+      target={target}
+      disabled={disabled}
+      addonEnd={icon ? { type: 'icon', value: icon } : undefined}
+      // The v2 resolver drops `Button`'s own `button` default, so an action would submit a form.
+      type="button"
+      data-testid={dataTestId}
+      onClick={onClick}
+    >
+      {label}
+    </Button>
+  );
+};
+
+export default CardWidgetAction;