@transferwise/components 46.103.1 → 46.104.0

package/src/listItem/Checkbox/ListItemCheckbox.story.tsx

@@ -0,0 +1,128 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { useState } from 'react';
+import List from '../../list';
+import { ListItem } from '../ListItem';
+import {
+  SB_LIST_ITEM_ADDITIONAL_INFO as INFO,
+  SB_LIST_ITEM_MEDIA as MEDIA,
+} from '../_stories/subcomponents';
+import type { ListItemCheckboxProps } from './ListItemCheckbox';
+import { fn } from 'storybook/test';
+
+const meta: Meta<ListItemCheckboxProps> = {
+  component: ListItem.Checkbox,
+  title: 'Content/ListItem/ListItem.Checkbox',
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
+  args: {
+    checked: false,
+    indeterminate: false,
+    value: 'checkbox',
+    name: 'checkbox',
+    onChange: fn(),
+    onFocus: fn(),
+    onBlur: fn(),
+  },
+  argTypes: {
+    checked: {
+      control: 'boolean',
+    },
+    indeterminate: {
+      control: 'boolean',
+    },
+    onChange: {
+      table: {
+        type: { summary: '(event: ChangeEvent<HTMLInputElement>) => void' },
+      },
+    },
+    onFocus: {
+      table: {
+        type: { summary: '(event: FocusEvent<HTMLInputElement>) => void' },
+      },
+    },
+    onBlur: {
+      table: {
+        type: { summary: '(event: FocusEvent<HTMLInputElement>) => void' },
+      },
+    },
+  },
+} satisfies Meta<ListItemCheckboxProps>;
+
+export default meta;
+
+type Story = StoryObj<ListItemCheckboxProps>;
+
+export const Playground: Story = {
+  tags: ['!autodocs'],
+  render: (args: ListItemCheckboxProps) => {
+    return (
+      <List>
+        <ListItem
+          title="List item with checkbox"
+          subtitle="Select this option"
+          media={MEDIA.avatarSingle}
+          control={<ListItem.Checkbox {...args} />}
+          additionalInfo={INFO.nonInteractive}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * Checkbox controls demonstrate different states including checked, unchecked, and indeterminate.
+ */
+export const States: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: function Render() {
+    const [isChecked0, setisChecked0] = useState(false);
+    const [isChecked1, setisChecked1] = useState(true);
+    const [isChecked2, setisChecked2] = useState(false);
+
+    return (
+      <List>
+        <ListItem
+          control={
+            <ListItem.Checkbox
+              checked={isChecked0}
+              onChange={() => setisChecked0((current) => !current)}
+            />
+          }
+          title="Unchecked option"
+          subtitle="This option is not selected"
+          media={MEDIA.avatarSingle}
+        />
+
+        <ListItem
+          control={
+            <ListItem.Checkbox
+              checked={isChecked1}
+              onChange={() => setisChecked1((current) => !current)}
+            />
+          }
+          title="Checked option"
+          subtitle="This option is selected"
+          media={MEDIA.avatarSingle}
+        />
+
+        <ListItem
+          control={
+            <ListItem.Checkbox
+              checked={isChecked2}
+              indeterminate
+              onChange={() => setisChecked2((current) => !current)}
+            />
+          }
+          title="Indeterminate option"
+          subtitle="This option is partially selected"
+          media={MEDIA.avatarSingle}
+        />
+      </List>
+    );
+  },
+};

package/src/listItem/Checkbox/ListItemCheckbox.tsx

@@ -0,0 +1,33 @@
+import { useContext } from 'react';
+import CheckboxButton, { type CheckboxButtonProps } from '../../checkboxButton/CheckboxButton';
+import { useListItemControl } from '../useListItemControl';
+import { ListItemContext } from '../ListItemContext';
+
+export type ListItemCheckboxProps = Pick<
+  CheckboxButtonProps,
+  'checked' | 'indeterminate' | 'onChange' | 'onBlur' | 'onFocus' | 'value' | 'name'
+>;
+
+/**
+ * This component allows for rendering a checkbox control within a fully interactive ListItem. <br />It's a thin wrapper around the
+ * [CheckboxButton component](https://storybook.wise.design/?path=/docs/actions-checkboxbutton--docs),
+ * but offers only a subset of its features in line with the ListItem's constraints. <br />
+ *
+ * Please refer to the [Design documentation](https://wise.design/components/list-item---checkbox) for details.
+ */
+export const Checkbox = function (props: ListItemCheckboxProps) {
+  const { baseItemProps } = useListItemControl('checkbox', { ...props });
+  const { ids, describedByIds } = useContext(ListItemContext);
+
+  return (
+    <CheckboxButton
+      {...props}
+      className="wds-list-item-control"
+      disabled={baseItemProps.disabled}
+      id={ids.control}
+      aria-describedby={describedByIds}
+    />
+  );
+};
+
+Checkbox.displayName = 'ListItem.Checkbox';

package/src/listItem/Checkbox/index.ts

@@ -0,0 +1,2 @@
+export type { ListItemCheckboxProps } from './ListItemCheckbox';
+export { Checkbox } from './ListItemCheckbox';

package/src/listItem/IconButton/ListItemIconButton.spec.tsx

@@ -0,0 +1,119 @@
+import { Edit } from '@transferwise/icons';
+import userEvent from '@testing-library/user-event';
+import { mockMatchMedia, render, screen } from '../../test-utils';
+import { ListItem, type ListItemProps } from '../ListItem';
+
+mockMatchMedia();
+
+describe('ListItem.IconButton', () => {
+  const renderWith = (overrides: Partial<ListItemProps> = {}) =>
+    render(<ListItem title="Test title" {...overrides} />);
+
+  describe('as button', () => {
+    it('renders as button by default', () => {
+      renderWith({
+        control: (
+          <ListItem.IconButton>
+            <Edit />
+          </ListItem.IconButton>
+        ),
+      });
+      expect(screen.getByRole('button')).toBeInTheDocument();
+    });
+
+    it('renders as button if onClick is provided', () => {
+      renderWith({
+        control: (
+          <ListItem.IconButton onClick={() => {}}>
+            <Edit />
+          </ListItem.IconButton>
+        ),
+      });
+
+      expect(screen.getByRole('button')).toBeInTheDocument();
+    });
+
+    it('handles onClick events', async () => {
+      const handleClick = jest.fn();
+      renderWith({
+        control: (
+          <ListItem.IconButton onClick={handleClick}>
+            <Edit />
+          </ListItem.IconButton>
+        ),
+      });
+
+      await userEvent.click(screen.getByRole('button'));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('is disabled when ListItem is disabled', async () => {
+      const handleClick = jest.fn();
+      renderWith({
+        disabled: true,
+        control: (
+          <ListItem.IconButton onClick={handleClick}>
+            <Edit />
+          </ListItem.IconButton>
+        ),
+      });
+
+      const button = screen.getByRole('button');
+      expect(button).toBeDisabled();
+      await userEvent.click(button);
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('as link', () => {
+    it('renders as link when href is provided', () => {
+      renderWith({
+        control: (
+          <ListItem.IconButton href="/test">
+            <Edit />
+          </ListItem.IconButton>
+        ),
+      });
+
+      expect(screen.getByRole('link')).toHaveAttribute('href', '/test');
+    });
+
+    it('supports target attribute for links', () => {
+      renderWith({
+        control: (
+          <ListItem.IconButton href="/test" target="_blank">
+            <Edit />
+          </ListItem.IconButton>
+        ),
+      });
+
+      const link = screen.getByRole('link');
+      expect(link).toHaveAttribute('target', '_blank');
+      expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+    });
+
+    it('is disabled when ListItem is disabled', async () => {
+      renderWith({
+        disabled: true,
+        control: (
+          <ListItem.IconButton href="/test">
+            <Edit />
+          </ListItem.IconButton>
+        ),
+      });
+      expect(screen.getByRole('link')).toHaveAttribute('aria-disabled', 'true');
+    });
+  });
+
+  it('renders children content', () => {
+    renderWith({
+      control: (
+        <ListItem.IconButton>
+          <Edit />
+        </ListItem.IconButton>
+      ),
+    });
+
+    expect(screen.getByTestId('edit-icon')).toBeInTheDocument();
+  });
+});

package/src/listItem/IconButton/ListItemIconButton.story.tsx

@@ -0,0 +1,284 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import ListItem from '..';
+import { Edit } from '@transferwise/icons';
+import { fn } from 'storybook/test';
+import List from '../../list';
+import {
+  SB_LIST_ITEM_ADDITIONAL_INFO as INFO,
+  SB_LIST_ITEM_MEDIA as MEDIA,
+  SB_LIST_ITEM_PROMPTS as PROMPTS,
+} from '../_stories/subcomponents';
+import { disableControls } from '../_stories/helpers';
+import type { ListItemIconButtonProps } from './ListItemIconButton';
+
+const hideControls = disableControls([
+  'onClick',
+  'children',
+  'className',
+  'addonStart',
+  'addonEnd',
+]);
+
+/**
+ * Use IconButton to provide compact action controls within a ListItem context using iconography.
+ *
+ * Refer to the [design documentation](https://wise.design/components/list-item) for more details.
+ */
+const meta: Meta<ListItemIconButtonProps> = {
+  component: ListItem.IconButton,
+  title: 'Content/ListItem/ListItem.IconButton',
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
+  args: {
+    partiallyInteractive: false,
+    priority: undefined,
+    type: undefined,
+    'aria-label': 'Edit details',
+    children: <Edit />,
+    href: undefined,
+    target: undefined,
+    onClick: fn(),
+  },
+  argTypes: {
+    children: {
+      description: 'Once of the [Icon components](https://transferwise.github.io/icons/).',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+      control: false,
+    },
+    priority: {
+      control: 'radio',
+      options: ['unset (undefined)', 'primary', 'secondary', 'tertiary', 'minimal'],
+      mapping: {
+        'unset (undefined)': undefined,
+      },
+      description: 'IconButton priority/style variant',
+    },
+    type: {
+      control: 'radio',
+      options: ['unset (undefined)', 'default', 'negative'],
+      mapping: {
+        'unset (undefined)': undefined,
+      },
+      description:
+        'Sets a visual hierarchy amongst the buttons displayed on the screen. <br /> **NB:** `negative` sentiment only affects the `primary` and `secondary` priorities.',
+    },
+    partiallyInteractive: {
+      control: 'boolean',
+      description: 'Whether the icon button allows partial interactivity in the ListItem',
+    },
+    href: {
+      control: 'text',
+      description: 'URL for icon button rendered as link',
+    },
+    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<ListItemIconButtonProps>;
+
+export default meta;
+
+type Story = StoryObj<ListItemIconButtonProps>;
+
+export const Playground: Story = {
+  tags: ['!autodocs'],
+  render: (args: ListItemIconButtonProps) => {
+    return (
+      <List>
+        <ListItem
+          title="List item title"
+          subtitle="Subtitle goes here"
+          media={MEDIA.avatarSingle}
+          control={<ListItem.IconButton {...args} />}
+          additionalInfo={INFO.nonInteractive}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * It's strongly encouraged to provide `aria-label` prop for the `IconButton` control to ensure it
+ * follows accessibility best practices.
+ * If not set, the component will provide accessible name via the `title`, `subtitle`, `valueTitle`
+ * and `valueSubtitle` props and accessible description via `additionalInfo` and `prompt`, which
+ * may not be descriptive enough for the screen readers users.
+ */
+export const AccessibleName: Story = {
+  args: {
+    children: <Edit />,
+    href: 'https://wise.com',
+    target: '_blank',
+    onClick: undefined,
+  },
+  argTypes: hideControls(),
+  render: (args: ListItemIconButtonProps) => {
+    return (
+      <List>
+        <ListItem
+          control={<ListItem.IconButton {...args} />}
+          title="List item with icon button link"
+          subtitle="IconButton rendered as anchor element"
+          media={MEDIA.avatarSingle}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * By default, ListItem is fully interactive, which means its whole surface is clickable
+ * and triggers the control. To remain WCAG-compliant there can be no nested interactive
+ * elements inside the item.<br />
+ *
+ * To work around this limitation, this control also allows for a partially interactive mode,
+ * which can be enabled via `partiallyInteractive` prop. Once set, only the control will
+ * remain interactive, which allows for interactive element to be attached to the
+ * `ListItem.AdditionalInfo`. This allows for more complex layouts while still providing a
+ * clear, accessible action point for users. <br />
+ *
+ * If you still require a fully interactive ListItem, you can alternatively use `ListItem.Prompt`
+ * which allows for a single instance of a link or an inline button.
+ *
+ * Refer to the [design documentation](https://wise.design/components/list-item#interaction) for details.
+ */
+export const Interactivity: Story = {
+  args: {
+    children: <Edit />,
+  },
+  argTypes: hideControls(['partiallyInteractive']),
+  render: (args: ListItemIconButtonProps) => {
+    return (
+      <List>
+        <ListItem
+          control={<ListItem.IconButton {...args} />}
+          title="Fully interactive ListItem"
+          subtitle="IconButton in fully interactive context"
+          media={MEDIA.avatarSingle}
+          additionalInfo={INFO.nonInteractive}
+          prompt={PROMPTS.interactive}
+        />
+
+        <ListItem
+          control={<ListItem.IconButton {...args} partiallyInteractive />}
+          title="Partially interactive ListItem"
+          subtitle="IconButton in partially interactive context"
+          media={MEDIA.avatarSingle}
+          additionalInfo={INFO.interactive}
+          prompt={PROMPTS.interactive}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * There are two different types of icon button – default and negative – designed to emphasise the nature of the action. <br />
+ * **NB:** Sentiment only applies to `primary` and `secondary` priorities. <br />
+ * [Design documentation](https://wise.design/components/icon-button#types)
+ */
+export const Sentiment: Story = {
+  argTypes: hideControls(['sentiment', 'priority']),
+  render: (args) => {
+    return (
+      <List>
+        <ListItem
+          control={<ListItem.IconButton {...args} priority="primary" type="default" />}
+          title="Default Sentiment - Primary"
+          subtitle="Default sentiment with primary priority"
+          media={MEDIA.avatarSingle}
+        />
+        <ListItem
+          control={<ListItem.IconButton {...args} priority="secondary" type="default" />}
+          title="Default Sentiment - Secondary"
+          subtitle="Default sentiment with secondary priority"
+          media={MEDIA.avatarSingle}
+        />
+        <ListItem
+          control={<ListItem.IconButton {...args} priority="primary" type="negative" />}
+          title="Negative Sentiment - Primary"
+          subtitle="Negative sentiment with primary priority"
+          media={MEDIA.avatarSingle}
+        />
+        <ListItem
+          control={<ListItem.IconButton {...args} priority="secondary" type="negative" />}
+          title="Negative Sentiment - Secondary"
+          subtitle="Negative sentiment with secondary priority"
+          media={MEDIA.avatarSingle}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * Priorities set a visual hierarchy amongst the buttons displayed on the
+ * screen to help more important buttons to take precedence over others. <br />
+ * [Design documentation](https://wise.design/components/icon-button#priorities)
+ */
+export const Priority: Story = {
+  argTypes: hideControls(['sentiment', 'priority']),
+  render: (args) => {
+    return (
+      <List>
+        <ListItem
+          title="Primary Priority"
+          subtitle="Primary priority (default)"
+          media={MEDIA.avatarSingle}
+          control={<ListItem.IconButton {...args} priority="primary" />}
+        />
+        <ListItem
+          title="Secondary Priority"
+          subtitle="Secondary priority"
+          media={MEDIA.avatarSingle}
+          control={<ListItem.IconButton {...args} priority="secondary" />}
+        />
+        <ListItem
+          title="Secondary Neutral Priority"
+          subtitle="Secondary neutral priority"
+          media={MEDIA.avatarSingle}
+          control={<ListItem.IconButton {...args} priority="tertiary" />}
+        />
+        <ListItem
+          title="Tertiary Priority"
+          subtitle="Tertiary priority"
+          media={MEDIA.avatarSingle}
+          control={<ListItem.IconButton {...args} priority="minimal" />}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * If `href` prop is set, the component will be automatically rendered as an HTML anchor element.
+ */
+export const AsAnchor: Story = {
+  args: {
+    children: <Edit />,
+    href: 'https://wise.com',
+    target: '_blank',
+    onClick: undefined,
+  },
+  argTypes: hideControls(),
+  render: (args: ListItemIconButtonProps) => {
+    return (
+      <List>
+        <ListItem
+          control={<ListItem.IconButton {...args} />}
+          title="List item with icon button link"
+          subtitle="IconButton rendered as anchor element"
+          media={MEDIA.avatarSingle}
+        />
+      </List>
+    );
+  },
+};

package/src/listItem/IconButton/ListItemIconButton.tsx

@@ -0,0 +1,73 @@
+import { clsx } from 'clsx';
+import { useContext, type ReactNode } from 'react';
+import IconButtonComp, { type IconButtonProps } from '../../iconButton';
+import { useListItemControl } from '../useListItemControl';
+import { ListItemContext } from '../ListItemContext';
+
+export type ListItemIconButtonProps = Pick<
+  IconButtonProps,
+  'priority' | 'type' | 'onClick' | 'href' | 'target' | 'aria-label'
+> & {
+  children: ReactNode;
+  partiallyInteractive?: boolean;
+};
+
+/**
+ * This component allows for rendering a IconButton control. It's a thin wrapper around the
+ * [IconButton component](https://storybook.wise.design/?path=/docs/actions-iconbutton--docs), but offers only
+ * a subset of its features in line with the ListItem's constraints. <br />
+ * <br />
+ * Please refer to the [Design documentation](https://wise.design/components/list-item---icon-button) for details.
+ */
+export const IconButton = function ({
+  priority = 'minimal',
+  'aria-label': ariaLabel,
+  ...props
+}: ListItemIconButtonProps) {
+  const { partiallyInteractive, ...restProps } = props;
+
+  const { ids, props: itemProps } = useContext(ListItemContext);
+  const { baseItemProps } = useListItemControl('icon-button', {
+    partiallyInteractive,
+    ...restProps,
+  });
+
+  const getAriaProps = () => {
+    const labelIds = [
+      itemProps.inverted ? ids.subtitle : ids.title,
+      itemProps.inverted ? ids.title : ids.subtitle,
+      itemProps.inverted ? ids.valueSubtitle : ids.valueTitle,
+      itemProps.inverted ? ids.valueTitle : ids.valueSubtitle,
+    ].join(' ');
+    const descriptorIds = [ids.additionalInfo, ids.prompt].join(' ');
+
+    if (ariaLabel) {
+      return {
+        'aria-label': ariaLabel,
+        'aria-describedby': labelIds.concat(descriptorIds),
+      };
+    }
+
+    return {
+      'aria-labelledby': labelIds,
+      'aria-describedby': descriptorIds,
+    };
+  };
+
+  return (
+    <IconButtonComp
+      {...restProps}
+      {...getAriaProps()}
+      className={clsx(
+        'wds-list-item-control',
+        !partiallyInteractive && props.href && 'wds-list-item-control_pseudo-element',
+      )}
+      id={ids.control}
+      size={40}
+      priority={priority}
+      disabled={baseItemProps.disabled}
+    />
+  );
+};
+
+IconButton.displayName = 'ListItem.IconButton';

package/src/listItem/IconButton/index.ts

@@ -0,0 +1,2 @@
+export type { ListItemIconButtonProps } from './ListItemIconButton';
+export { IconButton } from './ListItemIconButton';

package/src/listItem/Image/ListItemImage.spec.tsx

@@ -0,0 +1,30 @@
+import { render, screen } from '../../test-utils';
+import { ListItem, type ListItemProps } from '../ListItem';
+
+const renderWithMedia = (media: ListItemProps['media']) =>
+  render(<ListItem title="Test Title" media={media} />);
+
+describe('ListItem.Image', () => {
+  it('renders image with presentation role when no alt text', () => {
+    renderWithMedia(<ListItem.Image src="test-image.jpg" />);
+    expect(screen.getByRole('presentation')).toHaveAttribute('src', 'test-image.jpg');
+  });
+
+  it('renders image with img role when alt text provided', () => {
+    renderWithMedia(<ListItem.Image src="test-image.jpg" alt="Test image description" />);
+
+    const image = screen.getByRole('img');
+    expect(image).toHaveAttribute('alt', 'Test image description');
+    expect(image).toHaveAttribute('src', 'test-image.jpg');
+  });
+
+  it('renders image with loading prop', () => {
+    renderWithMedia(<ListItem.Image src="test-image.jpg" loading="lazy" />);
+    expect(screen.getByRole('presentation')).toHaveAttribute('loading', 'lazy');
+  });
+
+  it('renders image with className prop', () => {
+    renderWithMedia(<ListItem.Image src="test-image.jpg" className="custom-image-class" />);
+    expect(screen.getByRole('presentation')).toHaveClass('custom-image-class');
+  });
+});