@transferwise/components 46.157.1 → 46.159.0

package/src/Markup/Markup.tsx

@@ -4,7 +4,7 @@ import Link from '../Link';
 
 import { parseMarkup } from './utils/parseMarkup';
 import { type AllowLinksMode, isHrefAllowedByMode, sanitiseHref } from './utils/sanitise';
-import type { MarkupActions, MarkupNode, MarkupProps } from './Markup.types';
+import type { MarkupActionHandler, MarkupNode, MarkupProps } from './Markup.types';
 
 const PLACEHOLDER_REGEX = /\{\{(\w+)\}\}/g;
 
@@ -16,28 +16,31 @@ function substituteData(text: string, data: MarkupData): string {
   );
 }
 
+type OnAction = MarkupActionHandler | undefined;
+
 function renderNodes(
   nodes: MarkupNode[],
-  actions: MarkupActions | undefined,
+  onAction: OnAction,
   data: MarkupData | undefined,
   allowLinks: AllowLinksMode,
 ): React.ReactNode[] {
-  return nodes.map((node, index) => renderNode(node, actions, data, allowLinks, index));
+  return nodes.map((node, index) => renderNode(node, onAction, data, allowLinks, index));
 }
 
 function renderLinkNode(
   node: Extract<MarkupNode, { type: 'link' }>,
-  actions: MarkupActions | undefined,
+  onAction: OnAction,
   data: MarkupData | undefined,
   allowLinks: AllowLinksMode,
   key: number,
 ): React.ReactNode {
-  const children = renderNodes(node.children, actions, data, allowLinks);
+  const children = renderNodes(node.children, onAction, data, allowLinks);
 
-  if (node.action && actions?.[node.action]) {
+  if (node.action && onAction) {
+    const actionId = node.action;
     return (
       // eslint-disable-next-line jsx-a11y/click-events-have-key-events
-      <Link key={key} aria-label={node.accessibilityLabel} onClick={actions[node.action]}>
+      <Link key={key} aria-label={node.accessibilityLabel} onClick={() => onAction(actionId)}>
         {children}
       </Link>
     );
@@ -62,7 +65,7 @@ function renderLinkNode(
 
 function renderNode(
   node: MarkupNode,
-  actions: MarkupActions | undefined,
+  onAction: OnAction,
   data: MarkupData | undefined,
   allowLinks: AllowLinksMode,
   key: number,
@@ -83,29 +86,29 @@ function renderNode(
           className={`wds-markup-emphasis wds-markup-emphasis--${node.type}`}
           aria-label={node.accessibilityLabel}
         >
-          {renderNodes(node.children, actions, data, allowLinks)}
+          {renderNodes(node.children, onAction, data, allowLinks)}
         </em>
       );
     case 'strong':
       return (
         <strong key={key} className="wds-markup-strong" aria-label={node.accessibilityLabel}>
-          {renderNodes(node.children, actions, data, allowLinks)}
+          {renderNodes(node.children, onAction, data, allowLinks)}
         </strong>
       );
     case 'strikethrough':
       return (
         <del key={key} className="wds-markup-strikethrough" aria-label={node.accessibilityLabel}>
-          {renderNodes(node.children, actions, data, allowLinks)}
+          {renderNodes(node.children, onAction, data, allowLinks)}
         </del>
       );
     case 'paragraph':
       return (
         <p key={key} className="wds-markup-paragraph">
-          {renderNodes(node.children, actions, data, allowLinks)}
+          {renderNodes(node.children, onAction, data, allowLinks)}
         </p>
       );
     case 'link':
-      return renderLinkNode(node, actions, data, allowLinks, key);
+      return renderLinkNode(node, onAction, data, allowLinks, key);
   }
 }
 
@@ -138,7 +141,7 @@ export const Markup: React.FC<MarkupProps> = ({
   children,
   data,
   allowLinks = 'internal',
-  actions,
+  onAction,
   as,
   className,
   'data-testid': testId,
@@ -167,7 +170,7 @@ export const Markup: React.FC<MarkupProps> = ({
 
   return (
     <Element className={className} data-testid={testId}>
-      {renderNodes(tree, actions, data, allowLinks)}
+      {renderNodes(tree, onAction, data, allowLinks)}
     </Element>
   );
 };

package/src/Markup/Markup.types.ts

@@ -1,7 +1,5 @@
 import React from 'react';
 
-import type { LinkProps } from '../Link';
-
 export type MarkupNode =
   | { type: 'text'; content: string }
   | { type: 'newline' }
@@ -20,9 +18,20 @@ export type MarkupNode =
       children: MarkupNode[];
     };
 
-export type MarkupActionHandler = NonNullable<LinkProps['onClick']>;
+/**
+ * Callback signature for the `onAction` prop. Receives the action name from
+ * `<link action="name">` when clicked.
+ */
+export type MarkupActionHandler = (actionId: string) => void;
 
-export type MarkupActions = Record<string, MarkupActionHandler>;
+/**
+ * Per-prop Markup configuration that host components can accept via a `markupOptions`
+ * prop keyed by their text prop names (e.g. `{ title?: MarkupTextOptions; description?: MarkupTextOptions }`).
+ */
+export type MarkupTextOptions = {
+  data?: Record<string, string | number>;
+  allowLinks?: 'internal' | 'all' | 'none';
+};
 
 export interface MarkupProps {
   /**
@@ -45,9 +54,10 @@ export interface MarkupProps {
    * */
   allowLinks?: 'internal' | 'all' | 'none';
   /**
-   * Map of action names to click handlers for `<link action="name">` button-mode links.
+   * Callback invoked when a `<link action="name">` button-mode link is clicked.
+   * Receives the action name as argument.
    * */
-  actions?: MarkupActions;
+  onAction?: MarkupActionHandler;
   /**
    * Wrapper element. Defaults to `div` when the parsed tree contains `<paragraph>` nodes,
    * `span` otherwise. Set explicitly to override auto-detection.

package/src/Markup/_stories/Markup.docs.mdx

@@ -4,6 +4,66 @@ import { Meta, Source } from '@storybook/addon-docs/blocks';
 
 # Developer notes
 
+## Integrating Markup in host components
+
+To integrate any component with Markup (e.g. `title`, `description`), follow this pattern:
+
+1. **Add `onMarkupAction`** — if the component is expected to accept actions, add a single callback prop that the
+   component forwards to every internal `<Markup onAction={onMarkupAction}>` instance. The name of this prop must
+   remain consistent across components.
+
+2. **Add `markupOptions`** — an optional prop keyed by the text prop names, carrying per-prop Markup configuration
+   (`data`, `allowLinks`). `MarkupTextOptions` type is exposed by the component.
+
+<Source dark language="tsx" code={`
+  import Markup, { type MarkupActionHandler, type MarkupTextOptions } from '../Markup';
+
+  type MyComponentProps = {
+    title: ReactNode;
+    description?: ReactNode;
+    onMarkupAction?: MarkupActionHandler;
+    markupOptions?: {
+      title?: MarkupTextOptions;
+      description?: MarkupTextOptions;
+    };
+  };
+
+  function MyComponent({ title, description, onMarkupAction, markupOptions }: MyComponentProps) {
+    return (
+      <div>
+        <Markup onAction={onMarkupAction} {...markupOptions?.title}>
+          {title}
+        </Markup>
+
+        {description && (
+          <Markup onAction={onMarkupAction} {...markupOptions?.description}>
+            {description}
+          </Markup>
+        )}
+      </div>
+    );
+  }
+`} />
+
+Consumer usage:
+
+<Source
+  dark
+  language="tsx"
+  code={`
+  <MyComponent
+    title='Something went wrong. <link action="retry">Try again</link>.'
+    description='Your balance is {{amount}}.'
+    onMarkupAction={(actionId) => {
+      if (actionId === 'retry') refetch();
+    }}
+    markupOptions={{
+      description: { data: { amount: '£100.00' }, allowLinks: 'all' }
+    }}
+  />
+`}
+/>
+
 ## How parsing works
 
 The parser runs in two phases: **tokenise** then **parse**.

package/src/Markup/_stories/Markup.story.tsx

@@ -1,6 +1,5 @@
 import React, { useState } from 'react';
 import { Meta, StoryObj } from '@storybook/react-webpack5';
-import { action } from 'storybook/actions';
 
 import {
   createSandboxStory,
@@ -9,7 +8,6 @@ import {
 import { storySourceWithoutNoise } from '../../../.storybook/helpers';
 
 import { Markup } from '../Markup';
-import type { MarkupActionHandler } from '../Markup.types';
 
 export default {
   component: Markup,
@@ -58,8 +56,8 @@ export const WithLinks: Story = {
 };
 
 /**
- * Button-mode link using the `action` attribute. The handler is provided via the `actions` prop.
- * If the named action is missing from the map, the link degrades to plain text.
+ * Button-mode link using the `action` attribute. The handler is provided via the `onAction` prop.
+ * If `onAction` is not provided, the link degrades to plain text.
  * */
 export const WithLinksAsButtons = storySourceWithoutNoise<Story>({
   args: {
@@ -68,14 +66,15 @@ export const WithLinksAsButtons = storySourceWithoutNoise<Story>({
   render: function Render(args) {
     const [count, setCount] = useState(0);
 
-    const increment: MarkupActionHandler = (event) => {
-      action('Button event')(event);
-      setCount((prev) => prev + 1);
+    const handleAction = (actionId: string) => {
+      if (actionId === 'increment') {
+        setCount((prev) => prev + 1);
+      }
     };
 
     return (
       <>
-        <Markup actions={{ increment }}>{args.children}</Markup>
+        <Markup onAction={handleAction}>{args.children}</Markup>
         <output>{count}</output>
       </>
     );

package/src/Markup/index.ts

@@ -1,2 +1,7 @@
 export { default } from './Markup';
-export type { MarkupActionHandler, MarkupActions, MarkupNode, MarkupProps } from './Markup.types';
+export type {
+  MarkupActionHandler,
+  MarkupNode,
+  MarkupProps,
+  MarkupTextOptions,
+} from './Markup.types';

package/src/Popover/Popover.tsx

@@ -1,4 +1,3 @@
-import { useTheme } from '@wise/components-theming';
 import { clsx } from 'clsx';
 import { useRef, useState, cloneElement, useEffect, isValidElement, useId } from 'react';
 
@@ -9,10 +8,14 @@ import { logActionRequired } from '../utilities';
 
 /** @deprecated Use `"top" | "bottom"` instead. */
 type PopoverPreferredPlacementDeprecated =
+  | `${Position.TOP_LEFT}`
+  | `${Position.TOP_RIGHT}`
   | `${Position.LEFT_TOP}`
   | `${Position.RIGHT_TOP}`
   | `${Position.BOTTOM_RIGHT}`
-  | `${Position.BOTTOM_LEFT}`;
+  | `${Position.BOTTOM_LEFT}`
+  | `${Position.LEFT_BOTTOM}`
+  | `${Position.RIGHT_BOTTOM}`;
 
 export type PopoverPreferredPlacement =
   | `${Position.TOP}`
@@ -35,11 +38,15 @@ export interface PopoverProps {
 
 function resolvePlacement(preferredPlacement: PopoverPreferredPlacement) {
   switch (preferredPlacement) {
+    case 'top-left':
+    case 'top-right':
     case 'left-top':
     case 'right-top':
       return 'top';
     case 'bottom-left':
     case 'bottom-right':
+    case 'left-bottom':
+    case 'right-bottom':
       return 'bottom';
     default:
       return preferredPlacement;

package/src/_deprecated/OverlayHeader/OverlayHeader.tsx

@@ -1,9 +1,5 @@
-import { clsx } from 'clsx';
-
-import { Size } from '../../common';
-import { CloseButton } from '../../common/CloseButton';
-import FlowHeader from '../../common/FlowHeader';
 import Logo from '../../Logo';
+import FlowNavigation from '../../FlowNavigation';
 
 /**
  * @deprecated Use `FlowNavigation` component instead, with `steps={[]}`
@@ -22,20 +18,5 @@ const defaultLogo = <Logo />;
  * @deprecated Use `FlowNavigation` component instead
  */
 export default function OverlayHeader({ avatar, onClose, logo = defaultLogo }: OverlayHeaderProps) {
-  const closeButton = onClose && <CloseButton size={Size.LARGE} onClick={onClose} />;
-  return (
-    <div className="np-overlay-header d-flex justify-content-center">
-      <FlowHeader
-        className="np-overlay-header__content p-a-3"
-        leftContent={logo}
-        rightContent={
-          <div className={clsx('d-flex', 'align-items-center', 'order-2')}>
-            {avatar}
-            {avatar && closeButton && <span className={clsx('m-x-1')} />}
-            {closeButton}
-          </div>
-        }
-      />
-    </div>
-  );
+  return <FlowNavigation {...{ avatar, onClose, logo }} />;
 }

package/src/common/Panel/Panel.test.tsx

@@ -76,4 +76,21 @@ describe('Panel', () => {
 
   const getPanel = () => document.querySelector('.np-panel--open');
   const getArrow = () => document.querySelector('.np-panel__arrow');
+
+  describe('aligned placements', () => {
+    it.each<[PanelProps['position'], string]>([
+      [Position.TOP_LEFT, 'top-start'],
+      [Position.TOP_RIGHT, 'top-end'],
+      [Position.RIGHT_TOP, 'right-start'],
+      [Position.RIGHT_BOTTOM, 'right-end'],
+      [Position.BOTTOM_RIGHT, 'bottom-end'],
+      [Position.BOTTOM_LEFT, 'bottom-start'],
+      [Position.LEFT_BOTTOM, 'left-end'],
+      [Position.LEFT_TOP, 'left-start'],
+    ])('converts %s to floating-ui placement %s', (position, expectedPlacement) => {
+      render(<Panel {...props} position={position} />);
+
+      expect(getPanel()).toHaveAttribute('data-popper-placement', expectedPlacement);
+    });
+  });
 });

package/src/common/Panel/Panel.tsx

@@ -12,15 +12,15 @@ import { clsx } from 'clsx';
 import {
   CSSProperties,
   HTMLAttributes,
-  MutableRefObject,
   PropsWithChildren,
+  RefObject,
   SyntheticEvent,
   forwardRef,
   useContext,
   useRef,
 } from 'react';
 
-import { Position, PositionBottom, PositionLeft, PositionRight, PositionTop } from '..';
+import { Position, type FloatingPlacement, positionToPlacement } from '..';
 import Dimmer from '../../Dimmer';
 import { OverlayIdContext } from '../../Provider/overlay/OverlayIdProvider';
 
@@ -29,11 +29,19 @@ const POPOVER_OFFSET = 16;
 // By default the flip positioning explores only the opposite alternative. So if left is passed and there's no enough space
 // the right one gets chosen. If there's no space on both sides popover goes back to the initially chosen one left.
 // This mapping forces popover to try the four available positions before going back to the initial chosen one.
-const fallbackPlacements: Record<string, Placement[]> = {
+const fallbackPlacements: Record<Placement, Placement[]> = {
   [Position.TOP]: [Position.BOTTOM, Position.RIGHT, Position.LEFT],
   [Position.BOTTOM]: [Position.TOP, Position.RIGHT, Position.LEFT],
   [Position.LEFT]: [Position.RIGHT, Position.TOP, Position.BOTTOM],
   [Position.RIGHT]: [Position.LEFT, Position.TOP, Position.BOTTOM],
+  'top-start': ['bottom-start', 'top-end', 'bottom-end'],
+  'top-end': ['bottom-end', 'top-start', 'bottom-start'],
+  'bottom-start': ['top-start', 'bottom-end', 'top-end'],
+  'bottom-end': ['top-end', 'bottom-start', 'top-start'],
+  'left-start': ['right-start', 'left-end', 'right-end'],
+  'left-end': ['right-end', 'left-start', 'right-start'],
+  'right-start': ['left-start', 'right-end', 'left-end'],
+  'right-end': ['left-end', 'right-start', 'left-start'],
 };
 
 export type PanelProps = PropsWithChildren<{
@@ -42,8 +50,8 @@ export type PanelProps = PropsWithChildren<{
   altAxis?: boolean;
   open?: boolean;
   onClose?: (event: Event | SyntheticEvent) => void;
-  position?: PositionBottom | PositionLeft | PositionRight | PositionTop;
-  anchorRef: MutableRefObject<Element | null>;
+  position?: FloatingPlacement;
+  anchorRef: RefObject<Element | null>;
   anchorWidth?: boolean;
   considerHeight?: boolean;
 }> &
@@ -66,6 +74,7 @@ const Panel = forwardRef<HTMLDivElement, PanelProps>(function Panel(
   reference,
 ) {
   const arrowRef = useRef<HTMLDivElement | null>(null);
+  const floatingPlacement = positionToPlacement(position);
 
   const middleware = [];
 
@@ -73,10 +82,10 @@ const Panel = forwardRef<HTMLDivElement, PanelProps>(function Panel(
     middleware.push(offset(POPOVER_OFFSET));
   }
 
-  if (flip && fallbackPlacements[position]) {
+  if (flip && fallbackPlacements[floatingPlacement]) {
     middleware.push(
       flipMiddleware({
-        fallbackPlacements: fallbackPlacements[position],
+        fallbackPlacements: fallbackPlacements[floatingPlacement],
       }),
     );
   }
@@ -104,7 +113,7 @@ const Panel = forwardRef<HTMLDivElement, PanelProps>(function Panel(
   }
 
   const { refs, floatingStyles, placement, middlewareData } = useFloating({
-    placement: position,
+    placement: floatingPlacement,
     middleware,
     elements: {
       reference: anchorRef.current,

package/src/common/Panel/_stories/Panel.story.tsx

@@ -0,0 +1,182 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { screen, userEvent, within } from 'storybook/test';
+import { useRef, useState } from 'react';
+
+import Button from '../../../Button';
+import { Position } from '../../PropsValues/position';
+import Panel from '../Panel';
+
+export default {
+  component: Panel,
+  title: 'Dialogs/Panel',
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Panel is a low-level floating component used by Popover and ResponsivePanel. It supports all floating-ui placements.',
+      },
+    },
+    chromatic: {
+      delay: 500,
+    },
+  },
+} satisfies Meta<typeof Panel>;
+
+type Story = StoryObj<typeof Panel>;
+
+const PanelDemo = ({
+  position,
+  label,
+}: {
+  position: Parameters<typeof Panel>[0]['position'];
+  label: string;
+}) => {
+  const anchorRef = useRef<HTMLButtonElement>(null);
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div style={{ display: 'inline-block' }}>
+      <Button ref={anchorRef} onClick={() => setOpen((prev) => !prev)}>
+        {label}
+      </Button>
+      <Panel
+        open={open}
+        position={position}
+        anchorRef={anchorRef}
+        onClose={() => setOpen(false)}
+        aria-label={`Panel positioned ${label}`}
+      >
+        <div style={{ padding: '16px', maxWidth: '200px' }}>
+          Panel content positioned at <strong>{label}</strong>
+        </div>
+      </Panel>
+    </div>
+  );
+};
+
+export const AllPositions: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  render: () => (
+    <div
+      style={{
+        display: 'flex',
+        flexWrap: 'wrap',
+        gap: '48px',
+        justifyContent: 'center',
+        alignItems: 'center',
+        padding: '120px 80px',
+      }}
+    >
+      <PanelDemo position={Position.TOP} label="top" />
+      <PanelDemo position={Position.TOP_LEFT} label="top-left" />
+      <PanelDemo position={Position.TOP_RIGHT} label="top-right" />
+      <PanelDemo position={Position.RIGHT} label="right" />
+      <PanelDemo position={Position.RIGHT_TOP} label="right-top" />
+      <PanelDemo position={Position.RIGHT_BOTTOM} label="right-bottom" />
+      <PanelDemo position={Position.BOTTOM} label="bottom" />
+      <PanelDemo position={Position.BOTTOM_LEFT} label="bottom-left" />
+      <PanelDemo position={Position.BOTTOM_RIGHT} label="bottom-right" />
+      <PanelDemo position={Position.LEFT} label="left" />
+      <PanelDemo position={Position.LEFT_TOP} label="left-top" />
+      <PanelDemo position={Position.LEFT_BOTTOM} label="left-bottom" />
+    </div>
+  ),
+};
+
+const SinglePanelDemo = ({
+  position,
+  label,
+}: {
+  position: Parameters<typeof Panel>[0]['position'];
+  label: string;
+}) => {
+  const anchorRef = useRef<HTMLButtonElement>(null);
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div style={{ padding: '120px 250px' }}>
+      <Button ref={anchorRef} onClick={() => setOpen((prev) => !prev)}>
+        {label}
+      </Button>
+      <Panel
+        open={open}
+        position={position}
+        anchorRef={anchorRef}
+        onClose={() => setOpen(false)}
+        aria-label={`Panel positioned ${label}`}
+      >
+        <div style={{ padding: '16px', maxWidth: '200px' }}>
+          Panel content positioned at <strong>{label}</strong>
+        </div>
+      </Panel>
+    </div>
+  );
+};
+
+const openPanelPlay = async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+  const canvas = within(canvasElement);
+  await userEvent.click(canvas.getByRole('button'));
+  await screen.findByText(/Panel content positioned at/i);
+};
+
+export const Top: Story = {
+  render: () => <SinglePanelDemo position={Position.TOP} label="top" />,
+  play: openPanelPlay,
+};
+
+export const Right: Story = {
+  render: () => <SinglePanelDemo position={Position.RIGHT} label="right" />,
+  play: openPanelPlay,
+};
+
+export const Bottom: Story = {
+  render: () => <SinglePanelDemo position={Position.BOTTOM} label="bottom" />,
+  play: openPanelPlay,
+};
+
+export const Left: Story = {
+  render: () => <SinglePanelDemo position={Position.LEFT} label="left" />,
+  play: openPanelPlay,
+};
+
+export const TopLeft: Story = {
+  render: () => <SinglePanelDemo position={Position.TOP_LEFT} label="top-left" />,
+  play: openPanelPlay,
+};
+
+export const TopRight: Story = {
+  render: () => <SinglePanelDemo position={Position.TOP_RIGHT} label="top-right" />,
+  play: openPanelPlay,
+};
+
+export const RightTop: Story = {
+  render: () => <SinglePanelDemo position={Position.RIGHT_TOP} label="right-top" />,
+  play: openPanelPlay,
+};
+
+export const RightBottom: Story = {
+  render: () => <SinglePanelDemo position={Position.RIGHT_BOTTOM} label="right-bottom" />,
+  play: openPanelPlay,
+};
+
+export const BottomRight: Story = {
+  render: () => <SinglePanelDemo position={Position.BOTTOM_RIGHT} label="bottom-right" />,
+  play: openPanelPlay,
+};
+
+export const BottomLeft: Story = {
+  render: () => <SinglePanelDemo position={Position.BOTTOM_LEFT} label="bottom-left" />,
+  play: openPanelPlay,
+};
+
+export const LeftBottom: Story = {
+  render: () => <SinglePanelDemo position={Position.LEFT_BOTTOM} label="left-bottom" />,
+  play: openPanelPlay,
+};
+
+export const LeftTop: Story = {
+  render: () => <SinglePanelDemo position={Position.LEFT_TOP} label="left-top" />,
+  play: openPanelPlay,
+};