Add CarouselPagination component

.changeset/short-adults-know.md

@@ -0,0 +1,5 @@
+---
+'@sumup-oss/circuit-ui': minor
+---
+
+Added a new CarouselPagination component. Use it to display larger amounts of content in limited spaces by dividing it into multiple pieces to be discoverd by the users through interaction.

.eslintrc.js

@@ -47,18 +47,12 @@ module.exports = require('@sumup-oss/foundry/eslint')({
       },
     },
     {
-      files: ['**/*.stories.*'],
+      files: ['**/*.stories.*', '**/*.spec.*'],
       rules: {
         'import/no-relative-packages': 'off',
         'react-server-components/use-client': 'off',
       },
     },
-    {
-      files: ['**/*.spec.*'],
-      rules: {
-        'react-server-components/use-client': 'off',
-      },
-    },
     {
       files: ['packages/circuit-ui/components/legacy/**/*'],
       rules: {

.storybook/fixtures.ts

@@ -0,0 +1,22 @@
+export const images: { src: string; alt: string }[] = [
+  {
+    src: '/images/sumup-coffee-transaction.jpg',
+    alt: 'Next to a cup of coffee lays a phone showing a card transaction in the SumUp app',
+  },
+  {
+    src: '/images/sumup-product-catalog.jpg',
+    alt: 'A person holds a tablet showing a grid of products in the SumUp POS app. In the background, cakes and pastries sit on a table',
+  },
+  {
+    src: '/images/sumup-tablet-insights.jpg',
+    alt: 'A tablet shows sales insights in the SumUp POS app. On the table next to it are a SumUp Solo card reader with printer and two bowls with fruits',
+  },
+  {
+    src: '/images/sumup-solo-cradle.jpg',
+    alt: 'A SumUp Solo card reader sits in its charging cradle next to a tray of red, green and dark-brown mini tarts',
+  },
+  {
+    src: '/images/sumup-solo-printer.jpg',
+    alt: 'A person taps their phone onto a SumUp Solo card reader, perhaps to pay for the assortment of food around it on the table',
+  },
+];

packages/circuit-ui/components/Carousel/Carousel.spec.tsx

@@ -15,10 +15,12 @@
 
 import { describe, expect, it, vi } from 'vitest';
 
+import { images } from '../../../../.storybook/fixtures.js';
 import { axe, render, screen } from '../../util/test-utils.js';
 
 import { Carousel } from './Carousel.js';
-import { SLIDES } from './__fixtures__/index.js';
+
+const slides = images.map((image) => ({ image }));
 
 describe('Carousel', () => {
   const baseProps = {
@@ -37,7 +39,7 @@ describe('Carousel', () => {
   it('should render with children as a function', () => {
     const children = vi.fn(() => <h1>Carousel heading</h1>);
     render(
-      <Carousel slides={SLIDES} {...baseProps}>
+      <Carousel slides={slides} {...baseProps}>
         {children}
       </Carousel>,
     );
@@ -47,7 +49,7 @@ describe('Carousel', () => {
 
   it('should render with children as a node', () => {
     render(
-      <Carousel slides={SLIDES} {...baseProps}>
+      <Carousel slides={slides} {...baseProps}>
         <h1>Carousel heading</h1>
       </Carousel>,
     );
@@ -56,7 +58,7 @@ describe('Carousel', () => {
   });
 
   it('should have no accessibility violations', async () => {
-    const { container } = render(<Carousel slides={SLIDES} {...baseProps} />);
+    const { container } = render(<Carousel slides={slides} {...baseProps} />);
     const actual = await axe(container);
 
     expect(actual).toHaveNoViolations();

packages/circuit-ui/components/Carousel/Carousel.stories.tsx

@@ -15,6 +15,8 @@
 
 import { useState } from 'react';
 
+import { images } from '../../../../.storybook/fixtures.js';
+
 import { Container } from './components/Container/index.js';
 import { Slides } from './components/Slides/index.js';
 import { Slide } from './components/Slide/index.js';
@@ -32,7 +34,8 @@ import {
   ANIMATION_DURATION,
   SLIDE_DURATION,
 } from './constants.js';
-import { SLIDES } from './__fixtures__/index.js';
+
+const slides = images.map((image) => ({ image }));
 
 export default {
   title: 'Components/Carousel',
@@ -47,7 +50,7 @@ export const Stateful = (args: CarouselProps) => (
 );
 
 Stateful.args = {
-  slides: SLIDES,
+  slides,
   slideDuration: SLIDE_DURATION,
   animationDuration: ANIMATION_DURATION,
   aspectRatio: ASPECT_RATIO,
@@ -61,7 +64,7 @@ Stateful.args = {
 };
 
 export const Composed = () => {
-  const total = SLIDES.length;
+  const total = slides.length;
   const [step, setStep] = useState(0);
   const goBack = () => setStep(step === 0 ? total - 1 : step - 1);
   const goForward = () => setStep(step === total - 1 ? 0 : step + 1);
@@ -70,7 +73,7 @@ export const Composed = () => {
     <div style={{ width: '50vw' }}>
       <Container>
         <Slides>
-          {SLIDES.map(({ image }, index) => (
+          {slides.map(({ image }, index) => (
             <Slide
               key={image.src}
               index={index}
@@ -86,9 +89,9 @@ export const Composed = () => {
         </Slides>
         <Controls>
           <ButtonList>
-            <PrevButton label="Previous" onClick={goBack} />
+            <PrevButton onClick={goBack}>Previous</PrevButton>
             <Status style={{ marginLeft: 8 }} step={step} total={total} />
-            <NextButton label="Next" onClick={goForward} />
+            <NextButton onClick={goForward}>Next</NextButton>
           </ButtonList>
         </Controls>
       </Container>

packages/circuit-ui/components/Carousel/components/Slide/Slide.stories.tsx

@@ -26,17 +26,17 @@ export default {
 export const OnlyImage = (args: SlideProps) => (
   <Slide {...args}>
     <Image
-      src="/images/illustration-waves.jpg"
-      alt="Aerial photo of turbulent blue ocean waves"
+      src="/images/sumup-coffee-transaction.jpg"
+      alt="Next to a cup of coffee lays a phone showing a card transaction in the SumUp app"
     />
   </Slide>
 );
 
 export const TextAndImage = (args: SlideProps) => (
   <Slide {...args}>
     <Image
-      src="/images/illustration-waves.jpg"
-      alt="Aerial photo of turbulent blue ocean waves"
+      src="/images/sumup-solo-cradle.jpg"
+      alt="A SumUp Solo card reader sits in its charging cradle next to a tray of red, green and dark-brown mini tarts"
     />
     <Headline
       style={{

packages/circuit-ui/components/Carousel/components/SlideImage/SlideImage.spec.tsx

@@ -20,8 +20,8 @@ import { axe, render } from '../../../../util/test-utils.js';
 import { SlideImage } from './SlideImage.js';
 
 const image = {
-  src: '/images/illustration-waves.jpg',
-  alt: 'Aerial photo of turbulent blue ocean waves',
+  src: '/images/sumup-coffee-transaction.jpg',
+  alt: 'Next to a cup of coffee lays a phone showing a card transaction in the SumUp app',
 };
 
 describe('SlideImage', () => {

packages/circuit-ui/components/CarouselPagination/CarouselPagination.mdx

@@ -0,0 +1,25 @@
+import { Meta, Status, Props, Story } from '../../../../.storybook/components';
+import * as Stories from './CarouselPagination.stories';
+
+<Meta of={Stories} />
+
+# CarouselPagination
+
+<Status variant="stable" />
+
+The carousel pagination component allows users to navigate content that is divided into multiple slides or pages.
+
+<Story of={Stories.Base} />
+<Props />
+
+## Usage
+
+Consider adjusting the layout or using a different component if the number of slides/pages exceeds five.
+
+For inline use cases, create an illusion of continuity through cropped images or text, so users quickly understand that they can get more content by moving beyond the screen edge.
+
+Do not place the carousel pagination on busy, dynamic backgrounds (i.e. on images, illustrations), in order to ensure optimal contrast and discoverability.
+
+Ensure that content outside the viewport is searchable and becomes visible when focused. Consider lazy-loading content that is initially hidden to optimize performance.
+
+<Story of={Stories.Carousel} />

packages/circuit-ui/components/CarouselPagination/CarouselPagination.module.css

@@ -0,0 +1,55 @@
+.base {
+  display: flex;
+  padding: 0;
+  margin: 0;
+  list-style-type: none;
+}
+
+.cue {
+  display: block;
+  padding: var(--cui-spacings-byte);
+  background: none;
+  border: none;
+  border-radius: var(--cui-border-radius-pill);
+}
+
+a.cue,
+button.cue {
+  cursor: pointer;
+}
+
+.shape {
+  display: block;
+  width: var(--cui-spacings-kilo);
+  height: var(--cui-spacings-kilo);
+  background-color: var(--cui-fg-placeholder);
+  border-radius: var(--cui-border-radius-pill);
+  transition:
+    background-color var(--cui-transitions-default),
+    width var(--cui-transitions-default);
+}
+
+a.cue:hover .shape,
+button.cue:hover .shape {
+  background-color: var(--cui-fg-placeholder-hovered);
+}
+
+a.cue:active .shape,
+button.cue:active .shape {
+  background-color: var(--cui-fg-placeholder-pressed);
+}
+
+.cue[aria-current] .shape {
+  width: var(--cui-spacings-peta);
+  background-color: var(--cui-bg-strong);
+}
+
+a.cue[aria-current]:hover .shape,
+button.cue[aria-current]:hover .shape {
+  background-color: var(--cui-bg-strong-hovered);
+}
+
+a.cue[aria-current]:active .shape,
+button.cue[aria-current]:active .shape {
+  background-color: var(--cui-bg-strong-pressed);
+}

packages/circuit-ui/components/CarouselPagination/CarouselPagination.spec.tsx

@@ -0,0 +1,90 @@
+/**
+ * Copyright 2024, SumUp Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { createRef } from 'react';
+
+import { render, screen } from '../../util/test-utils.js';
+
+import { CarouselPagination } from './CarouselPagination.js';
+
+describe('CarouselPagination', () => {
+  const baseProps = {
+    slides: [
+      { id: 'foo', label: 'Foo' },
+      { id: 'bar', label: 'Bar' },
+      { id: 'baz', label: 'Baz' },
+    ],
+    currentId: 'foo',
+  };
+
+  it('should merge a custom class name with the default ones', () => {
+    const className = 'foo';
+    render(<CarouselPagination {...baseProps} className={className} />);
+    const list = screen.getByRole('list');
+    expect(list?.className).toContain(className);
+  });
+
+  it('should forward a ref', () => {
+    const ref = createRef<HTMLUListElement>();
+    render(<CarouselPagination {...baseProps} ref={ref} />);
+    const list = screen.getByRole('list');
+    expect(ref.current).toBe(list);
+  });
+
+  it('should render as buttons when the slides have onClick handlers', () => {
+    const slides = [
+      { id: 'foo', label: 'Foo', onClick: vi.fn() },
+      { id: 'bar', label: 'Bar', onClick: vi.fn() },
+      { id: 'baz', label: 'Baz', onClick: vi.fn() },
+    ];
+    render(<CarouselPagination {...baseProps} slides={slides} />);
+    const buttons = screen.getAllByRole('button');
+    expect(buttons).toHaveLength(slides.length);
+  });
+
+  it('should render as links when the slides have href attributes', () => {
+    const slides = [
+      { id: 'foo', label: 'Foo', href: '#foo', onClick: vi.fn() },
+      { id: 'bar', label: 'Bar', href: '#bar', onClick: vi.fn() },
+      { id: 'baz', label: 'Baz', href: '#baz', onClick: vi.fn() },
+    ];
+    render(<CarouselPagination {...baseProps} slides={slides} />);
+    const links = screen.getAllByRole('link');
+    expect(links).toHaveLength(slides.length);
+  });
+
+  it('should mark the current active item', () => {
+    const slides = [
+      { id: 'foo', label: 'Foo', href: '#foo' },
+      { id: 'bar', label: 'Bar', href: '#bar' },
+      { id: 'baz', label: 'Baz', href: '#baz' },
+    ];
+    render(<CarouselPagination {...baseProps} slides={slides} />);
+    const currentSlide = screen.getByRole('link', { name: /foo/i });
+    expect(currentSlide).toHaveAttribute('aria-current');
+  });
+
+  it('should mark the current active item with the provided type', () => {
+    const slides = [
+      { id: 'foo', label: 'Foo', href: '#foo' },
+      { id: 'bar', label: 'Bar', href: '#bar' },
+      { id: 'baz', label: 'Baz', href: '#baz' },
+    ];
+    render(<CarouselPagination {...baseProps} slides={slides} type="page" />);
+    const currentSlide = screen.getByRole('link', { name: /foo/i });
+    expect(currentSlide).toHaveAttribute('aria-current', 'page');
+  });
+});