@transferwise/components 46.103.1 → 46.105.0

package/src/header/Header.spec.tsx

@@ -1,95 +1,113 @@
 import { render, screen, userEvent } from '../test-utils';
-
-import Header from '.';
+import Header, { HeaderProps } from '.';
 
 describe('Header', () => {
-  it('can set header title', () => {
-    render(<Header title="Header title" />);
+  const defaultProps: HeaderProps = {
+    title: 'Header title',
+  };
+
+  const renderHeader = (props: Partial<HeaderProps> = {}) => {
+    return render(<Header {...defaultProps} {...props} />);
+  };
 
+  it('can set header title', () => {
+    renderHeader();
     expect(screen.getByText('Header title')).toBeInTheDocument();
   });
 
   it('can trigger header action', async () => {
     const onHeaderActionClick = jest.fn();
-
-    render(
-      <Header
-        title="Header title"
-        action={{
-          text: 'Click me!',
-          onClick: onHeaderActionClick,
-        }}
-      />,
-    );
+    renderHeader({
+      action: {
+        text: 'Click me!',
+        onClick: onHeaderActionClick,
+      },
+    });
 
     await userEvent.click(screen.getByRole('button', { name: 'Click me!' }));
-
     expect(onHeaderActionClick).toHaveBeenCalledTimes(1);
   });
 
   it('can set aria-label property for header action', async () => {
     const onHeaderActionClick = jest.fn();
-
-    render(
-      <Header
-        title="Header title"
-        action={{
-          'aria-label': 'Magic',
-          text: 'Click me!',
-          onClick: onHeaderActionClick,
-        }}
-      />,
-    );
+    renderHeader({
+      action: {
+        'aria-label': 'Magic',
+        text: 'Click me!',
+        onClick: onHeaderActionClick,
+      },
+    });
 
     await userEvent.click(screen.getByRole('button', { name: 'Magic' }));
-
     expect(onHeaderActionClick).toHaveBeenCalledTimes(1);
   });
 
   it('renders header action as a link when href is provided', () => {
-    render(
-      <Header
-        title="Header title"
-        action={{
-          'aria-label': 'Click me!',
-          text: 'I am a link',
-          href: 'https://wise.com',
-        }}
-      />,
-    );
+    renderHeader({
+      action: {
+        'aria-label': 'Click me!',
+        text: 'I am a link',
+        href: 'https://wise.com',
+      },
+    });
 
     const link = screen.getByRole('link', { name: 'Click me!' });
-
     expect(link).toHaveAttribute('href', 'https://wise.com');
   });
 
   it('renders header with h5 heading tag by default', () => {
-    render(<Header title="Header title" />);
-
+    renderHeader();
     expect(screen.getByRole('heading', { name: 'Header title', level: 5 })).toBeInTheDocument();
   });
 
   it('can render header with specific heading tag', () => {
-    render(<Header as="h3" title="Header title" />);
-
+    renderHeader({ as: 'h3' });
     expect(screen.getByRole('heading', { name: 'Header title', level: 3 })).toBeInTheDocument();
   });
 
-  it('runs onClick if specified even when it got href prop', async () => {
-    const callback = jest.fn();
+  it('renders header with group level', () => {
+    renderHeader({ level: 'group' });
+    const header = screen.getByRole('heading', { name: 'Header title' });
+    expect(header).toHaveClass('np-header--group');
+  });
+
+  it('warns if Header as legend is not inside a fieldset', () => {
+    const consoleWarnMock = jest.spyOn(console, 'warn').mockImplementation();
+
+    renderHeader({ as: 'legend' });
+
+    expect(consoleWarnMock).toHaveBeenCalledWith(
+      'Legends should be the first child in a fieldset, and this is not possible when including an action',
+    );
+
+    consoleWarnMock.mockRestore();
+  });
+
+  it('does not warn if Header as legend is inside a fieldset', () => {
+    const consoleWarnMock = jest.spyOn(console, 'warn').mockImplementation();
+
     render(
-      <Header
-        as="h3"
-        title="Header title"
-        action={{ text: 'Click me', href: '#', onClick: callback }}
-      />,
+      <fieldset>
+        <Header as="legend" title="Header title" />
+      </fieldset>,
     );
 
+    expect(consoleWarnMock).not.toHaveBeenCalled();
+
+    consoleWarnMock.mockRestore();
+  });
+
+  it('runs onClick if specified even when it got href prop', async () => {
+    const callback = jest.fn();
+    renderHeader({
+      as: 'h3',
+      action: { text: 'Click me', href: '#', onClick: callback },
+    });
+
     const button = screen.getByRole('link', { name: 'Click me' });
     expect(button).toBeInTheDocument();
 
     await userEvent.click(button);
-
     expect(callback).toHaveBeenCalledTimes(1);
   });
 });

package/src/header/Header.story.tsx

@@ -1,53 +1,207 @@
-import Header from './Header';
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import Header, { HeaderProps } from './Header';
+import { storyConfig } from '../test-utils';
 
-export default {
-  component: Header,
-  title: 'Typography/Header',
-};
+const withContainer = (Story: any) => (
+  <div style={{ display: 'flex', justifyContent: 'center' }}>
+    <Story />
+  </div>
+);
+
+/**
+ * Not all stories need access to all controls as it causes unnecessary UI noise.
+ */
+const hideControls = (args: string[]) =>
+  Object.fromEntries(args.map((item) => [item, { table: { disable: true } }]));
 
-export const Basic = () => {
-  return <Header title="Header title" />;
+/**
+ * Reusable render logic for wrapping `Header` in a `<fieldset>` if `as` is `legend`.
+ */
+const renderHeader = (args: HeaderProps) => {
+  if (args.as === 'legend') {
+    return (
+      <fieldset style={{ width: '100%' }}>
+        <Header {...args} />
+      </fieldset>
+    );
+  }
+  return <Header {...args} />;
 };
 
-export const WithAction = () => {
-  return (
+/**
+ * Helper to generate variants for `AllVariants` story.
+ */
+const renderVariants = () => (
+  <div
+    className="header-variants"
+    style={{ display: 'flex', flexWrap: 'wrap', gap: '16px', maxWidth: '1200px' }}
+  >
+    {(['h1', 'h2', 'h3', 'legend'] as const).map((as) => (
+      <Header key={as} as={as} title={`Header as ${as}`} />
+    ))}
+    {(['section', 'group'] as const).map((level) => (
+      <Header key={level} level={level} title={`Header level ${level}`} />
+    ))}
     <Header
-      title="Header title"
+      as="h2"
+      title="Header with Action"
       action={{
-        'aria-label': 'Magic',
-        text: 'Click me!',
-        onClick: () => alert('Action!'),
+        'aria-label': 'Action',
+        text: 'Action',
+        onClick: () => alert('Action clicked!'),
       }}
     />
-  );
-};
-
-export const WithActionAsLink = () => {
-  return (
     <Header
-      title="Header title"
+      as="h2"
+      title="Header with link"
       action={{
-        text: 'This is a link',
+        'aria-label': 'Action',
+        text: 'Action',
         href: 'https://wise.com',
       }}
     />
-  );
+  </div>
+);
+
+/**
+ * The stories below document the `Header` component, which is used to structure content and convey hierarchy. <br />
+ * For more details, refer to the [design documentation](https://wise.design/components/section-header).
+ */
+const meta: Meta<typeof Header> = {
+  component: Header,
+  title: 'Typography/Header',
+  argTypes: {
+    level: {
+      type: {
+        name: 'enum',
+        value: ['section', 'group'],
+      },
+      table: {
+        type: {
+          summary: 'HeaderLevel',
+        },
+      },
+      description: 'Defines the hierarchical level of the header.',
+    },
+    as: {
+      type: {
+        name: 'enum',
+        value: ['h1', 'h2', 'h3', 'legend'],
+      },
+      table: {
+        type: {
+          summary: 'HeaderAs',
+        },
+      },
+      description:
+        'Defines which HTML element the Header will render as. Use `legend` only as the first child of a `<fieldset>` — otherwise a warning will appear. The `action` prop is not supported with `legend`. You can also use heading tags like `h1`, `h2`, `h3`, or `header`.',
+    },
+    action: {
+      table: {
+        type: {
+          summary: 'HeaderAction',
+        },
+      },
+      description: 'Defines an optional action (e.g., button or link) associated with the header.',
+    },
+  },
+  args: {
+    title: 'Default Header',
+    level: 'group',
+    as: 'h1',
+    action: undefined,
+  },
+  tags: ['autodocs'],
+  decorators: [withContainer],
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
 };
 
-export const WithActionAsLinkPreventingNavigationWithTracking = () => {
-  return (
-    <Header
-      title="Header title"
-      action={{
-        text: 'This is a link',
-        href: 'https://wise.com',
-        onClick: (event: React.MouseEvent<HTMLElement>) => {
-          alert('Running onClick handler');
+export default meta;
 
-          // we can stop the navigation from happening as onClick will always run before href redirect
-          event.preventDefault();
-        },
-      }}
-    />
-  );
+type Story = StoryObj<typeof Header>;
+
+export const Playground: Story = {
+  render: renderHeader,
+  args: {
+    title: 'Playground Header',
+    level: 'group',
+    as: 'h2',
+    action: {
+      'aria-label': 'Action',
+      text: 'Click me',
+      onClick: () => alert('Action clicked!'),
+    },
+  },
+};
+
+/**
+ * Demonstrates a `Header` with an associated action.
+ */
+export const Action: Story = {
+  args: {
+    title: 'Header with Action',
+    action: {
+      'aria-label': 'Action',
+      text: 'Action',
+      onClick: () => alert('Action clicked!'),
+    },
+  },
+  argTypes: hideControls(['as', 'className', 'level', 'title', 'testId']),
 };
+
+/**
+ * Demonstrates a `Header` with an associated action as a link.
+ */
+export const ActionAsLink: Story = {
+  args: {
+    title: 'Header with Action as Link',
+    action: {
+      'aria-label': 'Learn more about this section',
+      text: 'Learn more',
+      href: 'https://wise.com',
+      target: '_blank',
+    },
+  },
+  argTypes: hideControls(['as', 'className', 'level', 'title', 'testId']),
+};
+
+/**
+ * Demonstrates a `Header` rendered as a custom HTML element.
+ */
+export const CustomElement: Story = {
+  render: renderHeader,
+  args: {
+    title: 'Legend Header',
+    as: 'legend',
+  },
+  argTypes: hideControls(['action', 'className', 'level', 'testId']),
+};
+
+/**
+ * Demonstrates a `Header` with a specific hierarchical level.
+ */
+export const SectionLevel: Story = {
+  args: {
+    title: 'Section Header',
+    level: 'section',
+  },
+  argTypes: hideControls(['action', 'as', 'className', 'title', 'testId']),
+};
+
+/**
+ * Displays all variants of the `Header` component, including different levels, tags, and actions.
+ */
+export const AllVariants = storyConfig(
+  {
+    tags: ['!autodocs'],
+    parameters: {
+      padding: '0',
+    },
+    render: renderVariants,
+  },
+  { variants: ['default', 'dark', 'bright-green', 'forest-green', 'rtl'] },
+);

package/src/header/Header.tsx

@@ -1,102 +1,133 @@
 import { clsx } from 'clsx';
 
-import { ActionButtonProps } from '../actionButton/ActionButton';
-import Button from '../button';
 import { AriaLabelProperty, CommonProps, Heading, LinkProps, Typography } from '../common';
+import Button from '../button';
 import Link from '../link';
 import Title from '../title';
-import { HTMLAttributes } from 'react';
+import React, { useEffect, useRef, FunctionComponent } from 'react';
 
 type ActionProps = AriaLabelProperty & {
   text: string;
+  onClick?: () => void;
 };
 
-type ButtonActionProps = ActionProps & ActionButtonProps;
-
+type ButtonActionProps = ActionProps;
 type LinkActionProps = ActionProps & LinkProps;
 
-export type HeaderProps = CommonProps & {
+export interface HeaderProps extends CommonProps {
   /**
-   * When the `href` property is provided to the `action`, we will render a `Link` instead of a `ActionButton`.
+   * Optional prop to define the action for the header. If the `href` property
+   * is provided, a `Link` will be rendered instead of a `Button`.
    */
   action?: ButtonActionProps | LinkActionProps;
+
   /**
-   * Override the heading element rendered for the title, useful to specify the semantics of your header.
+   * Option prop to specify DOM render element of the title
+   *
+   * - When `as="legend"`, the `Header` will render as a `<legend>` element.
+   *   **Note:** `<legend>` elements must be the first child of a `<fieldset>` to comply with HTML semantics.
+   *   If this condition is not met, a warning will be logged to the console.
    *
-   * @default "h5"
+   * - Other valid values include standard heading tags (`h1` to `h6`) or `header`.
    */
   as?: Heading | 'legend' | 'header';
+
+  /** Required prop to set the title of the Header. */
   title: string;
-} & Pick<HTMLAttributes<HTMLDivElement>, 'role' | 'id'>;
 
-const HeaderAction = ({ action }: { action: ButtonActionProps | LinkActionProps }) => {
-  const props = {
-    'aria-label': action['aria-label'],
-  };
+  /** Optional prop to specify the level of the Header */
+  level?: 'section' | 'group';
 
-  if ('href' in action) {
-    return (
-      <Link href={action.href} target={action.target} onClick={action.onClick} {...props}>
-        {action.text}
-      </Link>
-    );
-  }
+  className?: string;
+  testId?: string;
+}
 
+/**
+ * Renders a header action which can be either a button or a link.
+ *
+ * @param {Object} props - The properties object.
+ * @param {ButtonActionProps | LinkActionProps} props.action - The action object which can be either a button or a link.
+ * @returns {JSX.Element} The rendered header action component.
+ */
+const HeaderAction = React.forwardRef<
+  HTMLButtonElement | HTMLAnchorElement,
+  { action: ButtonActionProps | LinkActionProps }
+>(({ action }, ref) => {
   return (
-    <Button
-      className="np-header__button"
-      priority="tertiary"
-      size="sm"
+    <Link
+      className="np-header__action-button"
+      aria-label={action['aria-label']}
+      href={'href' in action ? action.href : undefined}
+      target={'target' in action ? action.target : undefined}
       onClick={action.onClick}
-      {...props}
     >
       {action.text}
-    </Button>
+    </Link>
   );
-};
+});
+
+HeaderAction.displayName = 'HeaderAction';
 
 /**
+ * @param {ButtonActionProps | LinkActionProps} [action] - Optional prop to specify the action button or link.
+ * @param {Heading | 'legend'} [as='h5'] - Optional prop to override the heading element rendered for the title.
+ * @param {string} title - Required prop to set the title of the section header.
+ * @param {'group' | 'section'} [level='group'] - Optional prop to specify the level of the section header.
+ * @param {string} [className]
+ * @param {string} [testId]
  *
- * Neptune Web: https://transferwise.github.io/neptune-web/components/content/Header
- *
+ * @see {@link Header } for further information.
+ * @see {@link https://storybook.wise.design/?path=/docs/typography-header--docs|Storybook Wise Design}
  */
-export const Header = ({
-  id,
-  action,
-  as = 'h5',
-  title,
-  className,
-  role = undefined,
-}: HeaderProps) => {
-  if (!action) {
-    return (
-      <Title
-        as={as}
-        id={id}
-        role={role}
-        type={Typography.TITLE_GROUP}
-        className={clsx('np-header', 'np-header__title', className)}
-      >
-        {title}
-      </Title>
-    );
-  }
+const Header: FunctionComponent<HeaderProps> = React.forwardRef(
+  (
+    { as = 'h5', action, className, testId, title, level = 'group', ...props },
+    ref: React.Ref<HTMLDivElement | HTMLHeadingElement | HTMLLegendElement>,
+  ) => {
+    const internalRef = useRef<HTMLLegendElement>(null);
+    const levelTypography =
+      level === 'group' ? Typography.TITLE_GROUP : Typography.TITLE_SUBSECTION;
+    const isLegendOrNoAction = !action || as === 'legend';
+    const headerClasses = clsx('np-header', className, {
+      'np-header--group': level === 'group',
+      'np-header__title': isLegendOrNoAction,
+    });
+
+    const commonProps = {
+      className: headerClasses,
+      'data-testid': testId,
+    };
+
+    useEffect(() => {
+      if (as === 'legend' && internalRef.current) {
+        const { parentElement } = internalRef.current;
+        if (!parentElement || parentElement.tagName.toLowerCase() !== 'fieldset') {
+          console.warn(
+            'Legends should be the first child in a fieldset, and this is not possible when including an action',
+          );
+        }
+      }
+    }, [as]);
 
-  if (as === 'legend') {
-    // eslint-disable-next-line no-console
-    console.warn(
-      'Legends should be the first child in a fieldset, and this is not possible when including an action',
+    if (!action) {
+      return (
+        <Title ref={internalRef} as={as} type={levelTypography} {...commonProps} {...props}>
+          {title}
+        </Title>
+      );
+    }
+
+    return (
+      <div {...commonProps} {...props} ref={ref as React.Ref<HTMLDivElement>}>
+        <Title as={as} type={levelTypography} className="np-header__title">
+          {title}
+        </Title>
+        <HeaderAction action={action} />
+      </div>
     );
-  }
+  },
+);
 
-  return (
-    <div className={clsx('np-header', className)}>
-      <Title as={as} type={Typography.TITLE_GROUP} id={id} className="np-header__title">
-        {title}
-      </Title>
-      <HeaderAction action={action} />
-    </div>
-  );
-};
+Header.displayName = 'Header';
 
 export default Header;

package/src/header/index.ts

@@ -1 +1,2 @@
 export { default } from './Header';
+export type { HeaderProps } from './Header';

package/src/i18n/cs.json

@@ -45,6 +45,7 @@
   "neptune.Upload.csFailureText": "Nahrání se nezdařilo. Zkuste to prosím později",
   "neptune.Upload.csSuccessText": "Úspěšně nahráno!",
   "neptune.Upload.csTooLargeMessage": "Nahrajte soubor menší než {maxSize} MB",
+  "neptune.Upload.csTooLargeNoLimitMessage": "Nahrajte menší soubor",
   "neptune.Upload.csWrongTypeMessage": "Tento formát souboru není podporován. Zkuste to znovu s jiným souborem",
   "neptune.Upload.psButtonText": "Zrušit",
   "neptune.Upload.psProcessingText": "Načítání...",
@@ -52,6 +53,7 @@
   "neptune.Upload.usButtonText": "Nebo vyberte soubor",
   "neptune.Upload.usDropMessage": "Přetáhněte soubor a zahajte nahrávání",
   "neptune.Upload.usPlaceholder": "Přetáhněte soubor menší než {maxSize} MB",
+  "neptune.Upload.usPlaceholderNoLimit": "Přetáhněte soubor",
   "neptune.UploadButton.allFileTypes": "Všechny typy souborů",
   "neptune.UploadButton.dropFiles": "Přetáhněte soubor a zahajte nahrávání",
   "neptune.UploadButton.instructions": "{fileTypes}, menší než {size} MB",

package/src/i18n/es.json

@@ -45,6 +45,7 @@
   "neptune.Upload.csFailureText": "La carga del archivo ha fallado. Por favor, inténtalo de nuevo",
   "neptune.Upload.csSuccessText": "¡Se ha subido el archivo!",
   "neptune.Upload.csTooLargeMessage": "Proporciona un archivo menor de {maxSize} MB",
+  "neptune.Upload.csTooLargeNoLimitMessage": "Proporciona un archivo más pequeño",
   "neptune.Upload.csWrongTypeMessage": "Tipo de archivo no aceptado. Por favor, inténtalo de nuevo con un archivo diferente",
   "neptune.Upload.psButtonText": "Cancela",
   "neptune.Upload.psProcessingText": "Subiendo...",
@@ -52,6 +53,7 @@
   "neptune.Upload.usButtonText": "O selecciona un archivo",
   "neptune.Upload.usDropMessage": "Arrastra un archivo para subirlo",
   "neptune.Upload.usPlaceholder": "Arrastra y suelta un archivo de menos de {maxSize} MB",
+  "neptune.Upload.usPlaceholderNoLimit": "Arrastra y suelta un archivo",
   "neptune.UploadButton.allFileTypes": "Todos los tipos de archivos",
   "neptune.UploadButton.dropFiles": "Arrastra un archivo para subirlo",
   "neptune.UploadButton.instructions": "{fileTypes}, menor que {size}MB",

package/src/i18n/th.json

@@ -45,6 +45,7 @@
   "neptune.Upload.csFailureText": "การอัปโหลดล้มเหลว กรุณาลองอีกครั้ง",
   "neptune.Upload.csSuccessText": "อัปโหลดเรียบร้อย!",
   "neptune.Upload.csTooLargeMessage": "กรุณาใช้ไฟล์ที่มีขนาดเล็กกว่า {maxSize} MB",
+  "neptune.Upload.csTooLargeNoLimitMessage": "โปรดอัปโหลดไฟล์ที่เล็กลง",
   "neptune.Upload.csWrongTypeMessage": "ไม่รองรับประเภทไฟล์ โปรดลองอีกครั้งโดยใช้ไฟล์อื่น",
   "neptune.Upload.psButtonText": "ยกเลิก",
   "neptune.Upload.psProcessingText": "กำลังอัปโหลด...",
@@ -52,6 +53,7 @@
   "neptune.Upload.usButtonText": "หรือเลือกไฟล์",
   "neptune.Upload.usDropMessage": "วางไฟล์เพื่อเริ่มการอัปโหลด",
   "neptune.Upload.usPlaceholder": "ลากและวางไฟล์ที่น้อยกว่า {maxSize} MB",
+  "neptune.Upload.usPlaceholderNoLimit": "ลากและวางไฟล์",
   "neptune.UploadButton.allFileTypes": "ไฟล์ทุกประเภท",
   "neptune.UploadButton.dropFiles": "วางไฟล์เพื่อเริ่มการอัปโหลด",
   "neptune.UploadButton.instructions": "{fileTypes} น้อยกว่า {size} MB",