@transferwise/components 46.165.5 → 46.167.0

package/src/CardContainer/CardContainer.css

@@ -0,0 +1,108 @@
+.wds-card-container {
+  --CardContainer-shadow: var(--CardContainer-theme-shadow, none);
+  --CardContainer-background-color: var(--color-background-screen);
+  --CardContainer-border-color: var(--color-border-neutral);
+  --CardContainer-border-radius: var(--radius-large);
+  --CardContainer-padding-block: var(--size-8);
+  --CardContainer-padding-inline: var(--size-8);
+  background-color: var(--CardContainer-background-color);
+  border: 1px solid var(--CardContainer-border-color);
+  border-radius: var(--CardContainer-border-radius);
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  padding-block: var(--CardContainer-padding-block);
+  padding-inline: var(--CardContainer-padding-inline);
+  inline-size: 100%;
+}
+@media (min-width: 840px) {
+  .wds-card-container {
+    --CardContainer-padding-block: var(--size-16);
+    --CardContainer-padding-inline: var(--size-16);
+  }
+}
+.wds-card-container--padding-none {
+  --CardContainer-padding-block: 0px;
+  --CardContainer-padding-inline: 0px;
+  overflow: clip;
+}
+.wds-card-container--active {
+  --CardContainer-background-color: var(--color-background-elevated);
+  --CardContainer-border-color: color-mix(in srgb, var(--color-border-neutral) 25%, transparent);
+  box-shadow: var(--CardContainer-shadow);
+}
+.wds-card-container--inactive {
+  --CardContainer-background-color: color-mix(in srgb, var(--color-background-neutral) 25%, transparent);
+  border-width: 0;
+  padding-block: calc(var(--CardContainer-padding-block) + 1px);
+  padding-inline: calc(var(--CardContainer-padding-inline) + 1px);
+  position: relative;
+}
+.wds-card-container--interactive:has(
+      > a[href]:hover,
+      > button:enabled:hover,
+      > a[href]:focus-visible,
+      > button:enabled:focus-visible
+    ).wds-card-container--active {
+  --CardContainer-border-color: color-mix(in srgb, var(--color-border-neutral) 75%, transparent);
+}
+.wds-card-container--interactive:has(
+      > a[href]:hover,
+      > button:enabled:hover,
+      > a[href]:focus-visible,
+      > button:enabled:focus-visible
+    ).wds-card-container--inactive {
+  --CardContainer-background-color: color-mix(in srgb, var(--color-background-neutral-hover) 25%, transparent);
+}
+.wds-card-container--interactive:has(> a[href]:active, > button:enabled:active).wds-card-container--active {
+  --CardContainer-border-color: var(--color-border-neutral);
+}
+.wds-card-container--interactive:has(> a[href]:active, > button:enabled:active).wds-card-container--inactive {
+  --CardContainer-background-color: color-mix(in srgb, var(--color-background-neutral-active) 25%, transparent);
+}
+.wds-card-container__border {
+  container-type: size;
+  inset: 0;
+  pointer-events: none;
+  position: absolute;
+}
+.wds-card-container__border svg {
+  display: block;
+  block-size: 100%;
+  inline-size: 100%;
+}
+.wds-card-container__border rect {
+  --CardContainer-border-dash-size: calc(var(--size-12) * 0.5);
+  --CardContainer-border-stroke-radius: calc(min(var(--CardContainer-border-radius), 50cqh, 50cqw) - 0.5px);
+  fill: none;
+  block-size: calc(100% - 1px);
+  rx: var(--CardContainer-border-stroke-radius);
+  ry: var(--CardContainer-border-stroke-radius);
+  stroke: var(--color-border-neutral);
+  stroke-dasharray: var(--CardContainer-border-dash-size) var(--CardContainer-border-dash-size);
+  inline-size: calc(100% - 1px);
+  x: 0.5px;
+  y: 0.5px;
+}
+/**
+ * The active spotlight's resting shadow, only designed for the light themes. Set on every theme
+ * root, as a nested ThemeProvider renders its own, so a card follows its nearest theme: a dark or
+ * green provider inside a light one turns the shadow off.
+ *
+ * There is no shadow or elevation token in @transferwise/neptune-tokens, so the value is
+ * component-scoped for now, the way PromoCard scopes `--Card-box-shadow`. It is the "Card Active
+ * shadow" effect style from Figma: `#0e0f0c` at 4%, kept literal so it doesn't drift with a
+ * theme's tokens. Collapses to a token reference once one is minted.
+ */
+.np-theme-personal {
+  --CardContainer-theme-shadow: 0 2px 12px rgba(14, 15, 12, 0.04), 0 2px 32px rgba(14, 15, 12, 0.04);
+}
+.np-theme-personal.np-theme-personal--dark,
+    .np-theme-personal.np-theme-personal--bright-green,
+    .np-theme-personal.np-theme-personal--forest-green,
+    .np-theme-personal.np-theme-business--dark,
+    .np-theme-personal.np-theme-business--bright-green,
+    .np-theme-personal.np-theme-business--forest-green,
+    .np-theme-personal.np-theme-platform--forest-green {
+  --CardContainer-theme-shadow: none;
+}

package/src/CardContainer/CardContainer.less

@@ -0,0 +1,171 @@
+// The hover and pressed states, as mixins so CardWidget can apply them to the card when only its
+// title is hovered or pressed. Applied to the card's root.
+.wds-card-container-hover-state() {
+  // The active spotlight keeps its resting shadow, and its hairline border strengthens.
+  &.wds-card-container--active {
+    --CardContainer-border-color: color-mix(in srgb, var(--color-border-neutral) 75%, transparent);
+  }
+
+  // The inactive spotlight's fill takes its hover value, at the same 25% strength as at rest.
+  &.wds-card-container--inactive {
+    --CardContainer-background-color: color-mix(
+      in srgb,
+      var(--color-background-neutral-hover) 25%,
+      transparent
+    );
+  }
+}
+
+.wds-card-container-pressed-state() {
+  // The active spotlight keeps its resting shadow, and its border is at full strength.
+  &.wds-card-container--active {
+    --CardContainer-border-color: var(--color-border-neutral);
+  }
+
+  // The inactive spotlight's fill takes its pressed value, at the same 25% strength as at rest.
+  &.wds-card-container--inactive {
+    --CardContainer-background-color: color-mix(
+      in srgb,
+      var(--color-background-neutral-active) 25%,
+      transparent
+    );
+  }
+}
+
+.wds-card-container {
+  // Resolved at the nearest theme root, below.
+  --CardContainer-shadow: var(--CardContainer-theme-shadow, none);
+  --CardContainer-background-color: var(--color-background-screen);
+  --CardContainer-border-color: var(--color-border-neutral);
+  --CardContainer-border-radius: var(--radius-large);
+  --CardContainer-padding-block: var(--size-8);
+  --CardContainer-padding-inline: var(--size-8);
+
+  background-color: var(--CardContainer-background-color);
+  border: 1px solid var(--CardContainer-border-color);
+  border-radius: var(--CardContainer-border-radius);
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  padding: var(--CardContainer-padding-block) var(--CardContainer-padding-inline);
+  width: 100%;
+
+  @media (--screen-md) {
+    --CardContainer-padding-block: var(--size-16);
+    --CardContainer-padding-inline: var(--size-16);
+  }
+
+  // Set through the padding variables, so the `inactive` spotlight's padding still composes.
+  // Length zeroes, as the inactive spotlight adds `1px` to these in `calc()`, which a unitless `0`
+  // would invalidate.
+  &--padding-none {
+    --CardContainer-padding-block: 0px;
+    --CardContainer-padding-inline: 0px;
+
+    // Full-bleed content has to follow the card's rounded corners. `overflow` leaves the card's
+    // own shadow alone, which `clip-path` would cut off.
+    overflow: clip;
+  }
+
+  &--active {
+    --CardContainer-background-color: var(--color-background-elevated);
+    // The raised surface's shadow already separates it, so its border is a softer hairline.
+    --CardContainer-border-color: color-mix(in srgb, var(--color-border-neutral) 25%, transparent);
+
+    box-shadow: var(--CardContainer-shadow);
+  }
+
+  &--inactive {
+    --CardContainer-background-color: color-mix(
+      in srgb,
+      var(--color-background-neutral) 25%,
+      transparent
+    );
+
+    // The dashed stroke is drawn inside the card instead of on a border, so the stroke isn't
+    // clipped with `padding="none"`. The padding takes the border's 1px, so content stays put.
+    border-width: 0;
+    padding: calc(var(--CardContainer-padding-block) + 1px)
+      calc(var(--CardContainer-padding-inline) + 1px);
+    position: relative;
+  }
+
+  // An `interactive` card follows its direct child link or button, such as a link that fills the
+  // card, so it only looks clickable where it can be clicked. Keyboard focus on the child shows the
+  // hover state too. A card without a spotlight has no hover or pressed state.
+  &--interactive:has(
+      > a[href]:hover,
+      > button:enabled:hover,
+      > a[href]:focus-visible,
+      > button:enabled:focus-visible
+    ) {
+    .wds-card-container-hover-state();
+  }
+
+  // Pressed state, while the same direct child is pressed. After the hover rule, so pressed wins
+  // while the pointer is down.
+  &--interactive:has(> a[href]:active, > button:enabled:active) {
+    .wds-card-container-pressed-state();
+  }
+
+  // Same treatment as ListItem's inactive spotlight: CSS `dashed` borders have a browser-chosen
+  // dash length, so the 6px/6px dashes are an SVG stroke along the card's edge.
+  &__border {
+    // A size container, so the stroke's corner radius can be capped by the card's height. An SVG
+    // `rect` clamps `rx` and `ry` separately, which turns the corners of a card shorter than twice
+    // the radius into ellipses, where `border-radius` keeps them round.
+    container-type: size;
+    inset: 0;
+    pointer-events: none;
+    position: absolute;
+
+    svg {
+      display: block;
+      height: 100%;
+      width: 100%;
+    }
+
+    rect {
+      --CardContainer-border-dash-size: calc(var(--size-12) * 0.5);
+      --CardContainer-border-stroke-radius: calc(
+        min(var(--CardContainer-border-radius), 50cqh, 50cqw) - 0.5px
+      );
+
+      fill: none;
+      height: calc(100% - 1px);
+      rx: var(--CardContainer-border-stroke-radius);
+      ry: var(--CardContainer-border-stroke-radius);
+      stroke: var(--color-border-neutral);
+      stroke-dasharray: var(--CardContainer-border-dash-size) var(--CardContainer-border-dash-size);
+      width: calc(100% - 1px);
+      x: 0.5px;
+      y: 0.5px;
+    }
+  }
+}
+
+/**
+ * The active spotlight's resting shadow, only designed for the light themes. Set on every theme
+ * root, as a nested ThemeProvider renders its own, so a card follows its nearest theme: a dark or
+ * green provider inside a light one turns the shadow off.
+ *
+ * There is no shadow or elevation token in @transferwise/neptune-tokens, so the value is
+ * component-scoped for now, the way PromoCard scopes `--Card-box-shadow`. It is the "Card Active
+ * shadow" effect style from Figma: `#0e0f0c` at 4%, kept literal so it doesn't drift with a
+ * theme's tokens. Collapses to a token reference once one is minted.
+ */
+.np-theme-personal {
+  --CardContainer-theme-shadow: 0 2px 12px rgb(14 15 12 / 4%), 0 2px 32px rgb(14 15 12 / 4%);
+
+  &:is(
+    .np-theme-personal--dark,
+    .np-theme-personal--bright-green,
+    .np-theme-personal--forest-green,
+    .np-theme-business--dark,
+    .np-theme-business--bright-green,
+    .np-theme-business--forest-green,
+    .np-theme-platform--forest-green
+  ) {
+    --CardContainer-theme-shadow: none;
+  }
+}

package/src/CardContainer/CardContainer.test.tsx

@@ -0,0 +1,150 @@
+import { render, screen, userEvent } from '../test-utils';
+import CardContainer from './CardContainer';
+import type { CardContainerSpotlight } from './CardContainer.types';
+
+describe('CardContainer', () => {
+  const content = 'Container content';
+
+  describe('rendering', () => {
+    it('renders children', () => {
+      render(<CardContainer>{content}</CardContainer>);
+      expect(screen.getByText(content)).toBeInTheDocument();
+    });
+
+    it('renders as a div by default', () => {
+      render(<CardContainer data-testid="container">{content}</CardContainer>);
+      expect(screen.getByTestId('container').tagName).toBe('DIV');
+    });
+
+    it.each(['section', 'article'] as const)('renders as %s when as is provided', (as) => {
+      render(
+        <CardContainer as={as} data-testid="container">
+          {content}
+        </CardContainer>,
+      );
+      expect(screen.getByTestId('container').tagName).toBe(as.toUpperCase());
+    });
+
+    it('applies className to the root element', () => {
+      render(
+        <CardContainer className="custom-class" data-testid="container">
+          {content}
+        </CardContainer>,
+      );
+      expect(screen.getByTestId('container')).toHaveClass('wds-card-container', 'custom-class');
+    });
+
+    it('spreads unknown props onto the root element', () => {
+      render(
+        <CardContainer aria-label="Cards" data-testid="container">
+          {content}
+        </CardContainer>,
+      );
+      expect(screen.getByTestId('container')).toHaveAttribute('aria-label', 'Cards');
+    });
+  });
+
+  describe('padding', () => {
+    it('has no padding modifier by default', () => {
+      render(<CardContainer data-testid="container">{content}</CardContainer>);
+      expect(screen.getByTestId('container')).not.toHaveClass('wds-card-container--padding-none');
+    });
+
+    it('renders the padding-none modifier', () => {
+      render(
+        <CardContainer padding="none" data-testid="container">
+          {content}
+        </CardContainer>,
+      );
+      expect(screen.getByTestId('container')).toHaveClass('wds-card-container--padding-none');
+    });
+
+    it('keeps the dashed border for the inactive spotlight without padding', () => {
+      render(
+        <CardContainer padding="none" spotlight="inactive" data-testid="container">
+          {content}
+        </CardContainer>,
+      );
+      expect(
+        screen.getByTestId('container').querySelector('.wds-card-container__border'),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('spotlight', () => {
+    it('has no spotlight modifier by default', () => {
+      render(<CardContainer data-testid="container">{content}</CardContainer>);
+      const root = screen.getByTestId('container');
+      expect(root).not.toHaveClass('wds-card-container--active');
+      expect(root).not.toHaveClass('wds-card-container--inactive');
+    });
+
+    it.each<CardContainerSpotlight>(['active', 'inactive'])(
+      'renders the %s spotlight modifier',
+      (spotlight) => {
+        render(
+          <CardContainer spotlight={spotlight} data-testid="container">
+            {content}
+          </CardContainer>,
+        );
+        expect(screen.getByTestId('container')).toHaveClass(`wds-card-container--${spotlight}`);
+      },
+    );
+
+    it('draws a decorative dashed border for the inactive spotlight', () => {
+      render(
+        <CardContainer spotlight="inactive" data-testid="container">
+          {content}
+        </CardContainer>,
+      );
+      expect(
+        screen.getByTestId('container').querySelector('.wds-card-container__border'),
+      ).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it.each<CardContainerSpotlight | undefined>(['active', undefined])(
+      'draws no dashed border for spotlight %s',
+      (spotlight) => {
+        render(
+          <CardContainer spotlight={spotlight} data-testid="container">
+            {content}
+          </CardContainer>,
+        );
+        const root = screen.getByTestId('container');
+        expect(root.querySelector('.wds-card-container__border')).not.toBeInTheDocument();
+      },
+    );
+  });
+
+  describe('interactive', () => {
+    it('is not interactive by default', () => {
+      render(<CardContainer data-testid="container">{content}</CardContainer>);
+      expect(screen.getByTestId('container')).not.toHaveClass('wds-card-container--interactive');
+    });
+
+    it('adds the interactive modifier without changing the element', () => {
+      render(
+        <CardContainer interactive data-testid="container">
+          <a href="/cards">{content}</a>
+        </CardContainer>,
+      );
+      const root = screen.getByTestId('container');
+      expect(root.tagName).toBe('DIV');
+      expect(root).toHaveClass('wds-card-container--interactive');
+      expect(root).not.toHaveAttribute('interactive');
+    });
+
+    it('spreads onClick onto the root element as a plain handler', async () => {
+      const onClick = jest.fn();
+      render(
+        <CardContainer data-testid="container" onClick={onClick}>
+          {content}
+        </CardContainer>,
+      );
+      const root = screen.getByTestId('container');
+      expect(root.tagName).toBe('DIV');
+      await userEvent.click(root);
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/CardContainer/CardContainer.tsx

@@ -0,0 +1,51 @@
+import { clsx } from 'clsx';
+import { forwardRef } from 'react';
+
+import type { CardContainerProps } from './CardContainer.types';
+
+/**
+ * A bounded surface that groups related content. It has no slots of its own: children are stacked
+ * with no gap between them. For a card with a title and actions, use `CardWidget`.
+ */
+const CardContainer = forwardRef<HTMLElement, CardContainerProps>(
+  (
+    {
+      spotlight,
+      padding = 'md',
+      interactive = false,
+      children,
+      as: Element = 'div',
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    return (
+      <Element
+        ref={ref as React.Ref<HTMLElement & HTMLDivElement>}
+        className={clsx(
+          'wds-card-container',
+          spotlight && `wds-card-container--${spotlight}`,
+          padding === 'none' && 'wds-card-container--padding-none',
+          interactive && 'wds-card-container--interactive',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+
+        {spotlight === 'inactive' && (
+          <span aria-hidden="true" className="wds-card-container__border">
+            <svg>
+              <rect />
+            </svg>
+          </span>
+        )}
+      </Element>
+    );
+  },
+);
+
+CardContainer.displayName = 'CardContainer';
+
+export default CardContainer;

package/src/CardContainer/CardContainer.types.ts

@@ -0,0 +1,62 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Highlights the card, matching `ListItem`'s `spotlight`.
+ *
+ * - `active` — live content the user can act on. Raised, with a soft shadow and a hairline border.
+ * - `inactive` — a feature the user has not set up yet. Recessed, with a dashed stroke.
+ *
+ * Without a spotlight the card is flat, with a solid stroke, for content that is present but not
+ * actionable.
+ */
+export type CardContainerSpotlight = 'active' | 'inactive';
+
+/**
+ * - `md` — 8px, and 16px from the `md` breakpoint up.
+ * - `none` — content runs to the card's edges.
+ */
+export type CardContainerPadding = 'md' | 'none';
+
+export interface CardContainerProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Highlights the card as live content (`active`) or as a feature not set up yet (`inactive`).
+   * Leave unset for a flat card.
+   * @default undefined
+   */
+  spotlight?: CardContainerSpotlight;
+
+  /**
+   * Space between the card's edge and its content. `none` lets content such as images or charts
+   * run to the card's edges, clipped to its rounded corners. Anything clipped at the edges
+   * includes focus rings, so use `none` for non-interactive content, and keep lists on `md`.
+   * @default 'md'
+   */
+  padding?: CardContainerPadding;
+
+  /**
+   * Content, stacked with no gap.
+   * @default undefined
+   */
+  children?: ReactNode;
+
+  /**
+   * Element rendered as the root. Use `section` when the card is a standalone, major part of the
+   * page, or `article` for self-contained content such as a feed item. Leave most cards as a `div`,
+   * so a page of cards doesn't fill the landmark list with a region per card.
+   * @default 'div'
+   */
+  as?: 'div' | 'section' | 'article';
+
+  /**
+   * Shows the card as hovered or pressed while a direct child link (with an `href`) or enabled
+   * button is, such as a link that fills the card, and as hovered while that child has keyboard
+   * focus. The rest of the card,
+   * and controls nested deeper, don't trigger the states, so the card is only shown as something
+   * to act on where it can be clicked.
+   * @default false
+   */
+  interactive?: boolean;
+
+  className?: string;
+  'data-testid'?: string;
+}