@transferwise/components 46.82.0 → 46.83.0

package/src/primitives/PrimitiveAnchor/src/PrimitiveAnchor.tsx

@@ -0,0 +1,122 @@
+import React, { forwardRef, useCallback } from 'react';
+import { clsx } from 'clsx';
+import type { PrimitiveAnchorProps } from '..';
+
+/**
+ * The Primitive `PrimitiveAnchor` component is customisable link element that can be
+ * used in various parts of the Wise Design System internally. It supports
+ * different states such as disabled and provides event handlers for common
+ * interactions like click, focus, blur, mouse enter, mouse leave, and key down.
+ *
+ * @see {@link PrimitiveAnchor} for further information.
+ * @see {@link https://storybook.wise.design/?path=/docs/primitive-anchor--docs|Storybook Wise Design}
+ */
+const PrimitiveAnchor = forwardRef<HTMLAnchorElement, PrimitiveAnchorProps>(
+  (
+    {
+      children,
+      className,
+      href,
+      id,
+      disabled = false,
+      testId,
+      onClick,
+      onFocus,
+      onBlur,
+      onMouseEnter,
+      onMouseLeave,
+      onKeyDown,
+      ...props
+    },
+    ref,
+  ) => {
+    const anchorClasses = clsx(
+      'wds-Anchor',
+      {
+        'wds-Anchor--disabled': disabled,
+      },
+      className,
+    );
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLAnchorElement>) => {
+        if (disabled) {
+          event.preventDefault();
+        } else {
+          onClick?.(event);
+        }
+      },
+      [disabled, onClick],
+    );
+
+    const handleFocus = useCallback(
+      (event: React.FocusEvent<HTMLAnchorElement>) => {
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: React.FocusEvent<HTMLAnchorElement>) => {
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
+
+    const handleMouseEnter = useCallback(
+      (event: React.MouseEvent<HTMLAnchorElement>) => {
+        onMouseEnter?.(event);
+      },
+      [onMouseEnter],
+    );
+
+    const handleMouseLeave = useCallback(
+      (event: React.MouseEvent<HTMLAnchorElement>) => {
+        onMouseLeave?.(event);
+      },
+      [onMouseLeave],
+    );
+
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLAnchorElement>) => {
+        onKeyDown?.(event);
+      },
+      [onKeyDown],
+    );
+
+    /**
+     * The following props are set to handle the `disabled` state for the link:
+     *
+     * - `aria-disabled`: Exposes the link as disabled to assistive technologies.
+     * - `href`: Removed when `disabled` is true to prevent navigation.
+     * - `role`: Set to 'link' when `disabled` is true to ensure the element
+     *    is still exposed as a link.
+     *
+     * For more details, refer to Scott O'Hara's article on disabling links:
+     * https://www.scottohara.me/blog/2021/05/28/disabled-links.html
+     */
+    const anchorProps = {
+      'aria-disabled': disabled,
+      className: anchorClasses,
+      'data-testid': testId,
+      href: disabled ? undefined : href,
+      id,
+      ref,
+      role: disabled ? 'link' : undefined,
+      rel: props.target === '_blank' ? 'noopener noreferrer' : undefined,
+      onClick: handleClick,
+      onFocus: handleFocus,
+      onBlur: handleBlur,
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave,
+      onKeyDown: handleKeyDown,
+      ...props,
+    };
+
+    return <a {...anchorProps}>{children}</a>;
+  },
+);
+
+PrimitiveAnchor.displayName = 'PrimitiveAnchor';
+
+export default PrimitiveAnchor;

package/src/primitives/PrimitiveAnchor/src/PrimitiveAnchor.types.ts

@@ -0,0 +1,28 @@
+import React, { ReactNode } from 'react';
+import { BasePrimitiveProps, StyleProp } from '../..';
+
+/**
+ * Type aliases for an anchor component.
+ */
+export type PrimitiveAnchorAttributes = React.AnchorHTMLAttributes<HTMLAnchorElement>;
+export type PrimitiveAnchorElementRef = React.Ref<HTMLAnchorElement>;
+
+/**
+ * Properties for the anchor component.
+ */
+export interface PrimitiveAnchorProps
+  extends BasePrimitiveProps,
+    StyleProp,
+    Omit<PrimitiveAnchorAttributes, 'role'> {
+  /** Content of the anchor */
+  children?: ReactNode;
+
+  /** The URL to navigate to when the anchor is clicked */
+  href: string;
+
+  /** Disable the anchor */
+  disabled?: boolean;
+
+  /** Reference to the anchor element */
+  ref?: PrimitiveAnchorElementRef;
+}

package/src/primitives/PrimitiveAnchor/src/index.ts

@@ -0,0 +1,6 @@
+export { default } from './PrimitiveAnchor';
+export type {
+  PrimitiveAnchorProps,
+  PrimitiveAnchorAttributes,
+  PrimitiveAnchorElementRef,
+} from './PrimitiveAnchor.types';

package/src/primitives/PrimitiveAnchor/stories/PrimitiveAnchor.story.tsx

@@ -0,0 +1,77 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { fn } from '@storybook/test';
+import PrimitiveAnchor from '..';
+
+export default {
+  component: PrimitiveAnchor,
+  title: 'Primitives/Anchor',
+  args: {
+    children: 'Click me',
+    href: 'https://example.com',
+    onClick: fn(),
+    onBlur: fn(),
+    onFocus: fn(),
+    onKeyDown: fn(),
+    onMouseEnter: fn(),
+    onMouseLeave: fn(),
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof PrimitiveAnchor>;
+
+type Story = StoryObj<typeof PrimitiveAnchor>;
+
+export const Basic: Story = {};
+
+export const WithLongName: Story = {
+  args: {
+    children: 'Anchor with a really long name',
+  },
+};
+
+export const WithCustomClass: Story = {
+  args: {
+    className: 'custom-class',
+  },
+  decorators: [
+    (Story) => (
+      <div>
+        <style>
+          {`
+            .custom-class {
+              background-color: red;
+              color: white;
+              border: 2px solid black;
+              padding: 10px 20px;
+              font-size: 16px;
+            }
+          `}
+        </style>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const WithTargetBlank: Story = {
+  args: {
+    target: '_blank',
+  },
+};
+
+export const WithRelNoopener: Story = {
+  args: {
+    rel: 'noopener noreferrer',
+  },
+};
+
+export const WithCustomStyle: Story = {
+  args: {
+    style: { color: 'red' },
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+};

package/src/primitives/PrimitiveAnchor/stories/PrimitiveAnchor.tests.story.tsx

@@ -0,0 +1,169 @@
+import { useState } from 'react';
+import { userEvent, within, expect } from '@storybook/test';
+import { Meta, StoryObj } from '@storybook/react';
+import PrimitiveAnchor from '..';
+
+const meta = {
+  title: 'Primitives/Anchor/Tests',
+  component: PrimitiveAnchor,
+  args: {
+    children: 'Click me',
+    href: 'https://example.com',
+  },
+} satisfies Meta<typeof PrimitiveAnchor>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const wait = async (duration = 500) =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, duration);
+  });
+
+export const ClickInteraction: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole('link');
+    await userEvent.click(link);
+    await expect(link).toHaveTextContent('Clicked!');
+  },
+  render: function Render(args) {
+    const [clicked, setClicked] = useState(false);
+
+    return (
+      <PrimitiveAnchor
+        {...args}
+        onClick={(event) => {
+          event.preventDefault();
+          setClicked(true);
+        }}
+      >
+        {clicked ? 'Clicked!' : 'Click me'}
+      </PrimitiveAnchor>
+    );
+  },
+};
+
+export const FocusInteraction: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole('link');
+    await userEvent.tab();
+    await expect(link).toHaveFocus();
+    await expect(link).toHaveTextContent('Focused!');
+  },
+  render: function Render(args) {
+    const [focused, setFocused] = useState(false);
+
+    return (
+      <PrimitiveAnchor {...args} onFocus={() => setFocused(true)}>
+        {focused ? 'Focused!' : 'Click me'}
+      </PrimitiveAnchor>
+    );
+  },
+};
+
+export const BlurInteraction: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole('link');
+    await userEvent.tab();
+    await expect(link).toHaveFocus();
+    await userEvent.tab();
+    await expect(link).not.toHaveFocus();
+    await expect(link).toHaveTextContent('Blurred!');
+  },
+  render: function Render(args) {
+    const [blurred, setBlurred] = useState(false);
+
+    return (
+      <PrimitiveAnchor {...args} onBlur={() => setBlurred(true)}>
+        {blurred ? 'Blurred!' : 'Click me'}
+      </PrimitiveAnchor>
+    );
+  },
+};
+
+export const MouseEnterInteraction: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole('link');
+    await expect(link).toHaveTextContent('Click me');
+    await userEvent.hover(link);
+    await expect(link).toHaveTextContent('Hovered!');
+  },
+  render: function Render(args) {
+    const [hovered, setHovered] = useState(false);
+
+    return (
+      <PrimitiveAnchor {...args} onMouseEnter={() => setHovered(true)}>
+        {hovered ? 'Hovered!' : 'Click me'}
+      </PrimitiveAnchor>
+    );
+  },
+};
+
+export const MouseLeaveInteraction: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole('link');
+    await expect(link).toHaveTextContent('Click me');
+    await userEvent.unhover(link);
+    await expect(link).toHaveTextContent('Left!');
+  },
+  render: function Render(args) {
+    const [left, setLeft] = useState(false);
+
+    return (
+      <PrimitiveAnchor {...args} onMouseLeave={() => setLeft(true)}>
+        {left ? 'Left!' : 'Click me'}
+      </PrimitiveAnchor>
+    );
+  },
+};
+
+export const KeyDownInteraction: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole('link');
+    await expect(link).toHaveTextContent('Click me');
+    await userEvent.tab();
+    await wait();
+    await userEvent.keyboard('{ArrowDown}');
+    await expect(link).toHaveTextContent('Key Pressed!');
+  },
+  render: function Render(args) {
+    const [keyPressed, setKeyPressed] = useState(false);
+
+    return (
+      <PrimitiveAnchor
+        {...args}
+        onKeyDown={(event) => {
+          if (event.key === 'ArrowDown') {
+            event.preventDefault();
+            setKeyPressed(true);
+          }
+        }}
+      >
+        {keyPressed ? 'Key Pressed!' : 'Click me'}
+      </PrimitiveAnchor>
+    );
+  },
+};
+
+export const TabIndexBehavior: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole('link');
+    await userEvent.tab();
+    await expect(link).not.toHaveFocus();
+  },
+  render: function Render(args) {
+    return (
+      <PrimitiveAnchor {...args} disabled tabIndex={-1}>
+        Click me
+      </PrimitiveAnchor>
+    );
+  },
+};

package/src/primitives/PrimitiveAnchor/test/PrimitiveAnchor.spec.tsx

@@ -0,0 +1,95 @@
+import { render, screen } from '@testing-library/react';
+import PrimitiveAnchor from '..';
+
+describe('PrimitiveAnchor', () => {
+  const defaultProps = {
+    children: 'Click me',
+    href: 'https://example.com',
+  };
+
+  const renderAnchor = (props?: Partial<typeof defaultProps>) => {
+    return render(<PrimitiveAnchor {...defaultProps} {...props} />);
+  };
+
+  it('renders an anchor by default', () => {
+    renderAnchor();
+    expect(screen.getByRole('link')).toBeInTheDocument();
+    expect(screen.getByRole('link')).toHaveTextContent('Click me');
+    expect(screen.getByRole('link')).toHaveAttribute('href', 'https://example.com');
+  });
+
+  it('applies the correct classes based on props', () => {
+    const props = {
+      ...defaultProps,
+      className: 'custom-class',
+    };
+
+    renderAnchor(props);
+
+    const link = screen.getByRole('link');
+    expect(link).toHaveClass('wds-Anchor');
+    expect(link).toHaveClass('custom-class');
+  });
+
+  it('disables the anchor when isDisabled is true', () => {
+    const props = {
+      ...defaultProps,
+      disabled: true,
+    };
+
+    renderAnchor(props);
+
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).toHaveClass('wds-Anchor--disabled');
+    expect(link).not.toHaveAttribute('href', 'https://example.com');
+  });
+
+  it('sets data-testid attribute', () => {
+    const props = {
+      ...defaultProps,
+      testId: 'custom-id',
+    };
+
+    renderAnchor(props);
+
+    const link = screen.getByTestId('custom-id');
+    expect(link).toBeInTheDocument();
+  });
+
+  it('sets the target attribute to _blank', () => {
+    const props = {
+      ...defaultProps,
+      target: '_blank',
+    };
+
+    renderAnchor(props);
+
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('target', '_blank');
+  });
+
+  it('sets the rel attribute to noopener noreferrer', () => {
+    const props = {
+      ...defaultProps,
+      rel: 'noopener noreferrer',
+    };
+
+    renderAnchor(props);
+
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  });
+
+  it('applies custom styles', () => {
+    const props = {
+      ...defaultProps,
+      style: { color: 'red' },
+    };
+
+    renderAnchor(props);
+
+    const link = screen.getByRole('link');
+    expect(link).toHaveStyle('color: red');
+  });
+});

package/src/primitives/PrimitiveButton/index.ts

@@ -0,0 +1,2 @@
+export { default } from './src';
+export * from './src';

package/src/primitives/PrimitiveButton/src/PrimitiveButton.tsx

@@ -0,0 +1,131 @@
+/* eslint-disable react/button-has-type */
+import React, { forwardRef, useCallback } from 'react';
+import { clsx } from 'clsx';
+import { useIntl, MessageDescriptor } from 'react-intl';
+import messages from '../../../i18n/commonMessages/Button.messages';
+import type { PrimitiveButtonProps } from '..';
+
+/**
+ * The Primitive `PrimitiveButton` component can be used in various parts the Wise Design
+ * System internally. It supports different states such as disabled and loading,
+ * and provides event handlers for common interactions like click, focus, blur,
+ * mouse enter, mouse leave, and keydown.
+ *
+ * @see {@link PrimitiveButton} for further information.
+ * @see {@link https://storybook.wise.design/?path=/docs/primitive-button--docs|Storybook Wise Design}
+ */
+const PrimitiveButton = forwardRef<HTMLButtonElement, PrimitiveButtonProps>(
+  (
+    {
+      children,
+      className,
+      id,
+      disabled = false,
+      loading = false,
+      testId,
+      type = 'button',
+      onClick,
+      onFocus,
+      onBlur,
+      onMouseEnter,
+      onMouseLeave,
+      onKeyDown,
+      ...props
+    },
+    ref,
+  ) => {
+    const intl = useIntl();
+    const classNames = clsx(
+      'wds-Button',
+      {
+        'wds-Button--disabled': disabled,
+        'wds-Button--loading': loading,
+      },
+      className,
+    );
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        if (disabled || loading) {
+          event.preventDefault();
+        } else {
+          onClick?.(event);
+        }
+      },
+      [disabled, loading, onClick],
+    );
+
+    const handleFocus = useCallback(
+      (event: React.FocusEvent<HTMLButtonElement>) => {
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: React.FocusEvent<HTMLButtonElement>) => {
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
+
+    const handleMouseEnter = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onMouseEnter?.(event);
+      },
+      [onMouseEnter],
+    );
+
+    const handleMouseLeave = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onMouseLeave?.(event);
+      },
+      [onMouseLeave],
+    );
+
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLButtonElement>) => {
+        onKeyDown?.(event);
+      },
+      [onKeyDown],
+    );
+
+    /**
+     * The following props are used to manage the `disabled` and `loading`
+     * states for the button:
+     *
+     * - `aria-disabled`: Communicates to assistive technologies that the button
+     *   is disabled when it is either disabled or loading.
+     * - `aria-label`: Provides an accessible label for the button, using a
+     *   localized loading message when the button is in a loading state.
+     * - `aria-live`: Ensures that updates to the button's content are announced
+     *   by assistive technologies, set to 'polite' during loading.
+     */
+    const buttonProps = {
+      'aria-disabled': disabled || loading,
+      'aria-label': loading
+        ? intl.formatMessage(messages.loadingAriaLabel as MessageDescriptor)
+        : props['aria-label'],
+      'aria-live': (loading ? 'polite' : 'off') as 'polite' | 'off' | 'assertive' | undefined,
+      className: classNames,
+      'data-testid': testId,
+      disabled,
+      id,
+      ref,
+      type,
+      onBlur: handleBlur,
+      onClick: handleClick,
+      onFocus: handleFocus,
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave,
+      onKeyDown: handleKeyDown,
+      ...props,
+    };
+
+    return <button {...buttonProps}>{children}</button>;
+  },
+);
+
+PrimitiveButton.displayName = 'PrimitiveButton';
+
+export default PrimitiveButton;

package/src/primitives/PrimitiveButton/src/PrimitiveButton.types.ts

@@ -0,0 +1,28 @@
+import React, { ReactNode } from 'react';
+import { BasePrimitiveProps, StyleProp } from '../..';
+
+/**
+ * Type aliases for a button component.
+ */
+export type PrimitiveButtonAttributes = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'role'>;
+export type PrimitiveButtonElementRef = React.Ref<HTMLButtonElement>;
+
+/**
+ * Properties for the Button component.
+ */
+export interface PrimitiveButtonProps
+  extends BasePrimitiveProps,
+    StyleProp,
+    PrimitiveButtonAttributes {
+  /** Content of the button */
+  children?: ReactNode;
+
+  /** Disable the button */
+  disabled?: boolean;
+
+  /** Loading state of the button */
+  loading?: boolean;
+
+  /** Reference to the button element */
+  ref?: PrimitiveButtonElementRef;
+}

package/src/primitives/PrimitiveButton/src/index.ts

@@ -0,0 +1,6 @@
+export { default } from './PrimitiveButton';
+export type {
+  PrimitiveButtonProps,
+  PrimitiveButtonAttributes,
+  PrimitiveButtonElementRef,
+} from './PrimitiveButton.types';