@transferwise/components 46.104.0 → 46.105.0

package/src/header/Header.accessibility.docs.mdx

@@ -0,0 +1,85 @@
+import { Meta, Canvas, Source } from '@storybook/addon-docs/blocks';
+import { NavigationOption } from '..';
+import { Bulb } from '@transferwise/icons';
+import * as stories from './Header.story';
+
+<Meta title="Typography/Header/Accessibility" />
+
+# Accessibility
+
+Given the `Header` is a key component for structuring content and conveying hierarchy, ensuring its accessibility is crucial for an inclusive experience.
+
+<NavigationOption
+  media={<Bulb size={24} />}
+  title="Design guidance"
+  content="Before you start, familiarise yourself with the dedicated accessibility documentation."
+  href="https://wise.design/components/section-header#accessibility"
+/>
+
+<br />
+<br />
+
+## Semantic headings
+
+The `Header` component should always use semantic HTML heading tags (`<h1>` to `<h6>`) to convey the document structure. Avoid using non-semantic tags unless absolutely necessary.
+
+<Source dark code={`
+// ✅ semantic heading
+<Header as="h1">Main heading</Header>
+
+// ⚠️ use with care
+
+<Header as="div">Non-semantic heading</Header>
+`}/>
+
+**Additional resources:**
+
+1. [Deque: Headings must follow a logical order](https://dequeuniversity.com/rules/axe/4.2/heading-order)
+2. [MDN: Using headings](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
+
+<br />
+
+## ARIA roles
+
+If the `Header` is used in a non-semantic context, ensure it is accessible by applying appropriate ARIA roles, such as `role="heading"`, and providing a `aria-level` attribute to indicate its level in the hierarchy.
+
+<Source
+  dark
+  code={`
+// ⚠️ use with care
+<Header as="div" role="heading" aria-level="1">
+  Main heading
+</Header>
+`}
+/>
+
+<br />
+
+## Accessibility with actions
+
+When using the `Header` with actions (e.g., buttons or links), ensure the actions are accessible by providing clear labels and ARIA attributes.
+
+<Source
+  dark
+  code={`
+// ✅ accessible action
+<Header
+  as="h2"
+  action={{
+    'aria-label': 'Edit section',
+    text: 'Edit',
+    onClick: () => alert('Edit clicked'),
+  }}
+>
+  Section heading
+</Header>
+`}
+/>
+
+<br />
+
+## Visual hierarchy
+
+Ensure the `Header` visually aligns with its semantic level. For example, an `<h1>` should be the largest and most prominent, while an `<h6>` should be the smallest.
+
+<Canvas of={stories.Playground} />

package/src/header/Header.css

@@ -1,26 +1,33 @@
 .np-header {
-  display: flex;
-  justify-content: space-between;
-  align-items: flex-end;
+  display: grid;
+  grid-template-columns: 1fr auto;
+  grid-column-gap: 24px;
+  grid-column-gap: var(--size-24);
+  -moz-column-gap: 24px;
+       column-gap: 24px;
+  -moz-column-gap: var(--size-24);
+       column-gap: var(--size-24);
+  align-items: center;
+  margin-bottom: 8px;
+  margin-bottom: var(--size-8);
   max-width: 100%;
   padding: 8px 0;
   padding: var(--size-8) 0;
+  width: 100%;
+}
+.np-header--group {
+  align-items: flex-end;
   border-bottom: 1px solid rgba(0,0,0,0.10196);
   border-bottom: 1px solid var(--color-border-neutral);
-  margin-bottom: 8px;
-  margin-bottom: var(--size-8);
-  -moz-column-gap: 24px;
-       column-gap: 24px;
-  -moz-column-gap: var(--size-24);
-       column-gap: var(--size-24);
 }
 .np-header__title {
   color: #5d7079;
   color: var(--color-content-secondary);
+  margin: 0;
 }
-.np-header__button {
-  margin-inline: calc(16px * -1);
-  margin-inline: calc(var(--size-16) * -1);
-  margin-bottom: calc(4px * -1);
-  margin-bottom: calc(var(--size-4) * -1);
+.np-header__action {
+  margin: 0;
+  height: 20px;
+  display: flex;
+  align-items: center;
 }

package/src/header/Header.less

@@ -1,20 +1,27 @@
 .np-header {
-  display: flex;
-  justify-content: space-between;
-  align-items: flex-end;
+  display: grid;
+  grid-template-columns: 1fr auto;
+  column-gap: var(--size-24);
+  align-items: center;
+  margin-bottom: var(--size-8);
   max-width: 100%;
   padding: var(--size-8) 0;
-  border-bottom: 1px solid var(--color-border-neutral);
-  margin-bottom: var(--size-8);
+  width: 100%;
+
+  &--group {
+    align-items: flex-end;
+    border-bottom: 1px solid var(--color-border-neutral);
+  }
 
   &__title {
     color: var(--color-content-secondary);
+    margin: 0;
   }
 
-  column-gap: var(--size-24);
-
-  &__button {
-    margin-inline: calc(var(--size-16) * -1);
-    margin-bottom: calc(var(--size-4) * -1);
+  &__action {
+    margin: 0;
+    height: 20px;
+    display: flex;
+    align-items: center;
   }
 }

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'] },
+);