feat(Pagination): add Pagination component aligned with Cyber skin

playroom/frame-component.tsx

@@ -22,6 +22,7 @@ import {
     VIVO_SKIN,
     BLAU_SKIN,
 } from '../src';
+import {CYBER_SKIN} from '../src/community';
 import {Movistar_New as defaultThemeConfig} from './themes';
 
 import type {ThemeConfig} from '../src';
@@ -62,6 +63,7 @@ const skinToLang: Record<string, string> = {
     [O2_SKIN]: 'en-GB',
     [O2_NEW_SKIN]: 'en-GB',
     [ESIMFLAG_SKIN]: 'es-ES',
+    [CYBER_SKIN]: 'es-ES',
 };
 
 const App = ({children, skinName}: {children: React.ReactNode; skinName: string}) => {

playroom/snippets.tsx

@@ -4583,6 +4583,27 @@ export default [
         name: 'NavigationBreadcrumbs',
         code: '<NavigationBreadcrumbs title="Facturas" breadcrumbs={[{title: "Cuenta", url: "/consumptions"}]} />',
     },
+    {
+        group: 'Pagination',
+        name: 'Pagination',
+        code: `
+            <Pagination
+                totalPages={10}
+                currentPage={getState("paginationPage", 3)}
+                onChange={(page) => setState("paginationPage", page)}
+            />`,
+    },
+    {
+        group: 'Pagination',
+        name: 'Pagination iconOnly',
+        code: `
+            <Pagination
+                totalPages={10}
+                mode="iconOnly"
+                currentPage={getState("paginationIconPage", 3)}
+                onChange={(page) => setState("paginationIconPage", page)}
+            />`,
+    },
     ...titlesSnippets,
     ...emptyStatesGroup,
     {

playroom/themes.tsx

@@ -16,10 +16,15 @@ export const O2_New: ThemeConfig = {...themes.O2_New, ...common};
 export const Telefonica: ThemeConfig = {...themes.Telefonica, ...common};
 export const Blau: ThemeConfig = {...themes.Blau, ...common};
 export const Esimflag: ThemeConfig = {...themes.Esimflag, ...common};
+export const Community_Cyber: ThemeConfig = {...themes.Cyber, ...common};
 
 export const Movistar_New_iOS: ThemeConfig = {...Movistar_New, platformOverrides: {platform: 'ios'}};
 export const Vivo_New_iOS: ThemeConfig = {...Vivo_New, platformOverrides: {platform: 'ios'}};
 export const O2_New_iOS: ThemeConfig = {...O2_New, platformOverrides: {platform: 'ios'}};
 export const Telefonica_iOS: ThemeConfig = {...Telefonica, platformOverrides: {platform: 'ios'}};
 export const Blau_iOS: ThemeConfig = {...Blau, platformOverrides: {platform: 'ios'}};
 export const Esimflag_iOS: ThemeConfig = {...Esimflag, platformOverrides: {platform: 'ios'}};
+export const Community_Cyber_iOS: ThemeConfig = {
+    ...Community_Cyber,
+    platformOverrides: {platform: 'ios'},
+};

src/__screenshot_tests__/pagination-screenshot-test.tsx

@@ -0,0 +1,46 @@
+import {openStoryPage, screen} from '../test-utils';
+
+import type {Device} from '../test-utils';
+
+const STORIES = [
+    {id: 'components-pagination--default', name: 'Default'},
+    {id: 'components-pagination--first-page', name: 'FirstPage'},
+    {id: 'components-pagination--last-page', name: 'LastPage'},
+    {id: 'components-pagination--with-ellipsis', name: 'WithEllipsis'},
+    {id: 'components-pagination--nav-only-responsive', name: 'NavOnlyResponsive'},
+    {id: 'components-pagination--pages-only', name: 'PagesOnly'},
+    {id: 'components-pagination--icon-only-controls', name: 'IconOnlyControls'},
+    {id: 'components-pagination--next-chapter-link', name: 'NextChapterLink'},
+];
+const DEVICES = ['DESKTOP', 'MOBILE_IOS'] as const;
+
+const getCases = () => {
+    const cases: Array<[string, string, Device]> = [];
+    for (const story of STORIES) {
+        for (const device of DEVICES) {
+            cases.push([story.name, story.id, device]);
+        }
+    }
+    return cases;
+};
+
+test.each(getCases())('Pagination %s - %s', async (_name, id, device) => {
+    await openStoryPage({id, device});
+
+    const pagination = await screen.findByTestId('Pagination');
+    const image = await pagination.screenshot();
+    expect(image).toMatchImageSnapshot();
+});
+
+// Compact view only renders below 375px viewport. We use MOBILE_IOS_SMALL (320px)
+// to drive the vertical layout and the current ± 1 page reduction.
+test('Pagination CompactView - MOBILE_IOS_SMALL', async () => {
+    await openStoryPage({
+        id: 'components-pagination--compact-view',
+        device: 'MOBILE_IOS_SMALL',
+    });
+
+    const pagination = await screen.findByTestId('Pagination');
+    const image = await pagination.screenshot();
+    expect(image).toMatchImageSnapshot();
+});

src/__stories__/pagination-story.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react';
+import {Pagination} from '..';
+
+export default {
+    title: 'Components/Pagination',
+};
+
+/**
+ * Mid-range page with both navigation controls. On desktop renders
+ * "Previous 1 2 3 4 ... 9 Next", on mobile collapses labels into chevrons.
+ */
+export const Default: StoryComponent = () => <Pagination totalPages={9} defaultPage={3} />;
+Default.storyName = 'Default';
+
+/**
+ * First page: the Previous control must be hidden (showPrevious logic).
+ */
+export const FirstPage: StoryComponent = () => <Pagination totalPages={10} defaultPage={1} />;
+FirstPage.storyName = 'FirstPage';
+
+/**
+ * Last page: the Next control must be hidden.
+ */
+export const LastPage: StoryComponent = () => <Pagination totalPages={10} defaultPage={10} />;
+LastPage.storyName = 'LastPage';
+
+/**
+ * Wide page count with active page in the middle: ellipses should appear on
+ * both sides of the visible range ("1 ... 9 10 11 ... 20").
+ */
+export const WithEllipsis: StoryComponent = () => <Pagination totalPages={20} defaultPage={10} />;
+WithEllipsis.storyName = 'WithEllipsis';
+
+/**
+ * No page list, only Previous/Next. On desktop the labels are visible,
+ * on mobile the labels are hidden and only chevrons are shown.
+ */
+export const NavOnlyResponsive: StoryComponent = () => (
+    <Pagination totalPages={10} defaultPage={5} hidePageList />
+);
+NavOnlyResponsive.storyName = 'NavOnlyResponsive';
+
+/**
+ * Page list without navigation controls. Matches the product-list scenario
+ * from the Figma examples panel.
+ */
+export const PagesOnly: StoryComponent = () => (
+    <Pagination totalPages={5} defaultPage={3} hideNavigationControls />
+);
+PagesOnly.storyName = 'PagesOnly';
+
+/**
+ * iconOnly mode forces chevron-only Previous/Next even on desktop.
+ * Combined with hidePageList matches the "Mapa / Listado" card scenario.
+ */
+export const IconOnlyControls: StoryComponent = () => (
+    <Pagination totalPages={10} defaultPage={5} mode="iconOnly" hidePageList />
+);
+IconOnlyControls.storyName = 'IconOnlyControls';
+
+/**
+ * Compact view: triggered automatically when the viewport is narrower than
+ * 375px (high-zoom or space-limited contexts). Layout stacks vertically with
+ * Previous / page list / Next and only renders the current ± 1 pages.
+ * Only visible when the screenshot test runs this story at MOBILE_IOS_SMALL.
+ */
+export const CompactView: StoryComponent = () => <Pagination totalPages={50} defaultPage={24} />;
+CompactView.storyName = 'CompactView';
+
+/**
+ * Pagination acting as a single next-chapter link: page list is hidden, only
+ * the Next control is rendered with a custom navRightLabel ("Siguiente
+ * capítulo"). Matches the chapter-reader scenario from the Figma examples.
+ */
+export const NextChapterLink: StoryComponent = () => (
+    <Pagination totalPages={10} defaultPage={1} hidePageList navRightLabel="Siguiente capítulo" />
+);
+NextChapterLink.storyName = 'NextChapterLink';

src/__tests__/pagination-test.tsx

@@ -0,0 +1,99 @@
+import * as React from 'react';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import ThemeContextProvider from '../theme-context-provider';
+import {makeTheme} from './test-utils';
+import Pagination, {getPaginationItems} from '../pagination';
+
+test('renders pagination navigation landmark', () => {
+    render(
+        <ThemeContextProvider theme={makeTheme()}>
+            <Pagination totalPages={5} defaultPage={1} />
+        </ThemeContextProvider>
+    );
+
+    expect(screen.getByRole('navigation', {name: 'Paginación - Página 1 de 5'})).toBeInTheDocument();
+});
+
+test('does not render when there is a single page', () => {
+    render(
+        <ThemeContextProvider theme={makeTheme()}>
+            <Pagination totalPages={1} />
+        </ThemeContextProvider>
+    );
+
+    expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
+});
+
+test('calls onChange when a page button is clicked (uncontrolled)', async () => {
+    const onChange = jest.fn();
+    render(
+        <ThemeContextProvider theme={makeTheme()}>
+            <Pagination totalPages={5} defaultPage={1} onChange={onChange} />
+        </ThemeContextProvider>
+    );
+
+    await userEvent.click(screen.getByRole('button', {name: 'Ir a la página 3'}));
+
+    expect(onChange).toHaveBeenCalledWith(3);
+});
+
+test('calls onChange when Next is clicked', async () => {
+    const onChange = jest.fn();
+    render(
+        <ThemeContextProvider theme={makeTheme()}>
+            <Pagination totalPages={5} defaultPage={2} onChange={onChange} />
+        </ThemeContextProvider>
+    );
+
+    await userEvent.click(screen.getByRole('button', {name: 'Página siguiente'}));
+
+    expect(onChange).toHaveBeenCalledWith(3);
+});
+
+test('does not change page when disabled', async () => {
+    const onChange = jest.fn();
+    render(
+        <ThemeContextProvider theme={makeTheme()}>
+            <Pagination totalPages={5} defaultPage={1} onChange={onChange} disabled />
+        </ThemeContextProvider>
+    );
+
+    await userEvent.click(screen.getByRole('button', {name: 'Ir a la página 3'}));
+
+    expect(onChange).not.toHaveBeenCalled();
+});
+
+test('honors controlled currentPage', () => {
+    render(
+        <ThemeContextProvider theme={makeTheme()}>
+            <Pagination totalPages={5} currentPage={3} />
+        </ThemeContextProvider>
+    );
+
+    // The current page is rendered as an aria-disabled button so VoiceOver can
+    // still land on it and announce "Página 3, página actual" — but the
+    // "Ir a la página 3" navigation button is absent (it's not navigable).
+    expect(screen.queryByRole('button', {name: 'Ir a la página 3'})).not.toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'Página 3, página actual'})).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'Ir a la página 2'})).toBeInTheDocument();
+});
+
+describe('getPaginationItems', () => {
+    test('returns an empty array for a single page', () => {
+        expect(getPaginationItems({totalPages: 1, currentPage: 1})).toEqual([]);
+    });
+
+    test('returns all pages when total fits without ellipsis', () => {
+        const items = getPaginationItems({totalPages: 5, currentPage: 3});
+        expect(items.filter((i) => i.type === 'ellipsis')).toHaveLength(0);
+        expect(items).toHaveLength(5);
+    });
+
+    test('inserts ellipsis when middle pages are skipped', () => {
+        const items = getPaginationItems({totalPages: 20, currentPage: 10});
+        expect(items.some((i) => i.type === 'ellipsis')).toBe(true);
+        expect(items[0]).toMatchObject({type: 'page', page: 1});
+        expect(items[items.length - 1]).toMatchObject({type: 'page', page: 20});
+    });
+});

src/index.tsx

@@ -63,6 +63,7 @@ export {default as Inline} from './inline';
 export {default as HorizontalScroll} from './horizontal-scroll';
 export {default as Stepper} from './stepper';
 export {ProgressBar, ProgressBarStepped} from './progress-bar';
+export {default as Pagination} from './pagination';
 export {default as Meter} from './meter';
 export {Rating, InfoRating} from './rating';
 export {VerticalMosaic, HorizontalMosaic} from './mosaic';