feat(component.pagination): Add new component pagination

packages/design/components/pagination/design-pagination.mdx

@@ -0,0 +1,37 @@
+## Preview
+
+<osds-pagination current="5" total-pages="9"></osds-pagination>
+
+## Description
+
+Pagination helps to separate an important quantity of data into multiple pages, having links to the relative pages.
+
+## Anatomy
+
+Five areas are included in the component :
+
+- Previous page arrow Button (presented as disabled)
+- First page number Button
+- Selected page Button
+- (in situations) Truncated pagination (ellipsis Button)
+- Next page arrow Button
+
+## Colors
+
+Only one color is applied on the Pagination: Primary.
+The primary color from your theme is applied.
+
+## Sizes
+
+The Pagination exists in a unique size SM.
+
+## Behaviours
+
+A Pagination can be focused, hovered and disabled.
+Current page Button has a selected styling, yet it is a not clickable Button (as readonly). Ellispsis Buttons are also not clickable.
+If the selected page number is the first page, the previous page arrow Button is disabled; same thing applies with the last page as selected and the next page arrow Button disabled.
+
+## Accessibility
+
+All Buttons are accessible via tabulation controls.
+You can select the page by pressing space or enter.

packages/libraries/core/scripts/generate-typedoc-md.js

@@ -29,6 +29,7 @@ const components = [
   'OdsLink',
   'OdsLocationTile',
   'OdsMessage',
+  'OdsPagination',
   'OdsQuantity',
   'OdsRadio',
   'OdsRadioButton',

packages/libraries/core/src/components/pagination/ods-pagination-attributes.ts

@@ -0,0 +1,21 @@
+import { OdsComponentAttributes } from '../ods-component-attributes';
+
+export interface OdsPaginationAttributes extends OdsComponentAttributes {
+  /**
+   * indicates if the pagination is entirely disabled.
+   * it means no interactions (hover, click, focus, etc)
+   */
+  disabled: boolean;
+  /**
+   * Its corresponding default current page. If no current page, it will be this page selected by default.
+   */
+  defaultCurrent?: number;
+  /**
+   * Its corresponding current page.
+   */
+  current: number;
+  /**
+   * The total amount of pages
+   */
+  totalPages: number;
+}

packages/libraries/core/src/components/pagination/ods-pagination-controller.spec.ts

@@ -0,0 +1,128 @@
+import { OdsClearLoggerSpy, OdsInitializeLoggerSpy, OdsLoggerSpyReferences } from '@ovhcloud/ods-testing/src';
+
+import { OdsLogger } from '../../logger/ods-logger';
+import { OdsPagination } from './ods-pagination';
+import { OdsPaginationController } from './ods-pagination-controller';
+import { OdsPaginationMock } from './ods-pagination-mock';
+
+describe('spec:ods-pagination-controller', () => {
+  let controller: OdsPaginationController;
+  let component: OdsPagination;
+  let loggerSpyReferences: OdsLoggerSpyReferences;
+
+  function setup(attributes: Partial<OdsPagination> = {}) {
+    component = { ...component, ...attributes };
+    controller = new OdsPaginationController(component);
+  }
+
+  beforeEach(() => {
+    component = new OdsPaginationMock();
+
+    const loggerMocked = new OdsLogger('myLoggerMocked');
+    loggerSpyReferences = OdsInitializeLoggerSpy({
+      loggerMocked: loggerMocked as never,
+      spiedClass: OdsPaginationController,
+    });
+  });
+
+  afterEach(() => {
+    OdsClearLoggerSpy(loggerSpyReferences);
+    jest.clearAllMocks();
+  });
+
+  describe('methods', () => {
+    describe('createPageList', () => {
+      it('should generate the correct number of pages', async () => {
+        const attributes = { disabled: false, current: 2, totalPages: 8 };
+        setup(attributes);
+        const pageList = controller.createPageList(component.totalPages, component.current);
+        expect(pageList).toHaveLength(8);
+      });
+
+      it('should generate the correct page list', async () => {
+        const attributes = { disabled: false, current: 2, totalPages: 9 };
+        setup(attributes);
+        const pageList = controller.createPageList(component.totalPages, component.current);
+
+        expect(pageList).toHaveLength(9);
+        expect(pageList[0].id).toEqual(1);
+        expect(pageList[1].id).toEqual(2);
+        expect(pageList[2].id).toEqual(3);
+        expect(pageList[3].id).toEqual(4);
+        expect(pageList[4].id).toEqual(5);
+        expect(pageList[5].id).toEqual(6);
+        expect(pageList[6].id).toEqual(7);
+        expect(pageList[7].id).toEqual(8);
+        expect(pageList[8].id).toEqual(9);
+      });
+
+      it('should display the correct page list following to the current page 5', async () => {
+        const attributes = { disabled: false, current: 5, totalPages: 9 };
+        setup(attributes);
+        const pageList = controller.createPageList(component.totalPages, component.current);
+
+        expect(pageList).toHaveLength(9);
+        expect(pageList[0].active).toBeTruthy();
+        expect(pageList[1].active).toBeFalsy();
+        expect(pageList[2].active).toBeFalsy();
+        expect(pageList[3].active).toBeTruthy();
+        expect(pageList[4].active).toBeTruthy();
+        expect(pageList[5].active).toBeTruthy();
+        expect(pageList[6].active).toBeFalsy();
+        expect(pageList[7].active).toBeFalsy();
+        expect(pageList[8].active).toBeTruthy();
+      });
+
+      it('should display the correct page list following to the current page 2', async () => {
+        const attributes = { disabled: false, current: 2, totalPages: 9 };
+        setup(attributes);
+        const pageList = controller.createPageList(component.totalPages, component.current);
+
+        expect(pageList).toHaveLength(9);
+        expect(pageList[0].active).toBeTruthy();
+        expect(pageList[1].active).toBeTruthy();
+        expect(pageList[2].active).toBeTruthy();
+        expect(pageList[3].active).toBeTruthy();
+        expect(pageList[4].active).toBeTruthy();
+        expect(pageList[5].active).toBeFalsy();
+        expect(pageList[6].active).toBeFalsy();
+        expect(pageList[7].active).toBeFalsy();
+        expect(pageList[8].active).toBeTruthy();
+      });
+
+      it('should display the correct page list following to the current page 3', async () => {
+        const attributes = { disabled: false, current: 3, totalPages: 9 };
+        setup(attributes);
+        const pageList = controller.createPageList(component.totalPages, component.current);
+
+        expect(pageList).toHaveLength(9);
+        expect(pageList[0].active).toBeTruthy();
+        expect(pageList[1].active).toBeTruthy();
+        expect(pageList[2].active).toBeTruthy();
+        expect(pageList[3].active).toBeTruthy();
+        expect(pageList[4].active).toBeTruthy();
+        expect(pageList[5].active).toBeFalsy();
+        expect(pageList[6].active).toBeFalsy();
+        expect(pageList[7].active).toBeFalsy();
+        expect(pageList[8].active).toBeTruthy();
+      });
+
+      it('should display the correct page list following to the current page 4', async () => {
+        const attributes = { disabled: false, current: 4, totalPages: 9 };
+        setup(attributes);
+        const pageList = controller.createPageList(component.totalPages, component.current);
+
+        expect(pageList).toHaveLength(9);
+        expect(pageList[0].active).toBeTruthy();
+        expect(pageList[1].active).toBeTruthy();
+        expect(pageList[2].active).toBeTruthy();
+        expect(pageList[3].active).toBeTruthy();
+        expect(pageList[4].active).toBeTruthy();
+        expect(pageList[5].active).toBeFalsy();
+        expect(pageList[6].active).toBeFalsy();
+        expect(pageList[7].active).toBeFalsy();
+        expect(pageList[8].active).toBeTruthy();
+      });
+    });
+  });
+});

packages/libraries/core/src/components/pagination/ods-pagination-controller.ts

@@ -0,0 +1,60 @@
+import { OdsComponentController } from '../ods-component-controller';
+import { OdsPagination } from './ods-pagination';
+
+/**
+ * common controller logic for pagination component used by the different implementations.
+ * it contains all the glue between framework implementation and the third party service.
+ */
+export class OdsPaginationController extends OdsComponentController<OdsPagination> {
+  constructor(component: OdsPagination) {
+    super(component);
+  }
+
+  createPageList(totalPages: number, pageSelected: number) {
+    let pageList = [];
+    for (let i = 1; i <= totalPages; i++) {
+      pageList.push({ id: i, active: false });
+    }
+
+    let startIndex = Math.max(pageSelected - 2, 1);
+    let endIndex = Math.min(startIndex + 4, totalPages);
+
+    if (totalPages <= 5) {
+      for (let i = 0; i < pageList.length; i++) {
+        pageList[i].active = true;
+      }
+    } else {
+      // >6
+      if (totalPages - pageSelected < 2) {
+        // last pages of a long list
+        startIndex = totalPages - 4;
+      }
+      if (totalPages > 5 && endIndex - startIndex < 4) {
+        if (startIndex === 1) {
+          endIndex = Math.min(startIndex + 5, totalPages);
+        } else if (endIndex === totalPages) {
+          startIndex = Math.max(endIndex - 5, 1);
+        }
+      }
+
+      for (let i = startIndex; i <= endIndex; i++) {
+        if (i == pageSelected - 2 && pageSelected < totalPages - 1 && pageSelected > 4 && pageSelected < totalPages - 2) {
+          continue;
+        }
+        if (i == pageSelected + 2 && pageSelected < totalPages - 3 && i > 5) {
+          continue;
+        }
+        pageList[i - 1].active = true;
+      }
+
+      if (startIndex > 1) {
+        pageList[0].active = true;
+      }
+
+      if (endIndex < totalPages) {
+        pageList[totalPages - 1].active = true;
+      }
+    }
+    return pageList;
+  }
+}

packages/libraries/core/src/components/pagination/ods-pagination-current-change-event-detail.ts

@@ -0,0 +1,4 @@
+export interface OdsPaginationCurrentChangeEventDetail {
+  current: number;
+  oldCurrent?: number;
+}

packages/libraries/core/src/components/pagination/ods-pagination-current-change-event.ts

@@ -0,0 +1,3 @@
+import { OdsPaginationCurrentChangeEventDetail } from './ods-pagination-current-change-event-detail';
+
+export type OdsPaginationCurrentChangeEvent = CustomEvent<OdsPaginationCurrentChangeEventDetail>;

packages/libraries/core/src/components/pagination/ods-pagination-default-attributes.ts

@@ -0,0 +1,14 @@
+// import { OdsThemeColorIntent } from '@ovhcloud/ods-theming';
+import { OdsPaginationAttributes } from './ods-pagination-attributes';
+
+/**
+ * default attribute values of pagination
+ */
+export const odsPaginationDefaultAttributesDoc: OdsPaginationAttributes = {
+  disabled: false,
+  defaultCurrent: undefined,
+  current: 1,
+  totalPages: 1,
+} as const;
+
+export const odsPaginationDefaultAttributes = odsPaginationDefaultAttributesDoc as unknown as OdsPaginationAttributes;

packages/libraries/core/src/components/pagination/ods-pagination-events.ts

@@ -0,0 +1,9 @@
+import { OdsComponentEvents } from '../ods-component-events';
+import { OdsPaginationCurrentChangeEventDetail } from './ods-pagination-current-change-event-detail';
+
+export interface OdsPaginationEvents extends OdsComponentEvents {
+  /**
+   * Emitted when the value has changed
+   */
+  odsCurrentChange: OdsPaginationCurrentChangeEventDetail;
+}

packages/libraries/core/src/components/pagination/ods-pagination-methods.ts

@@ -0,0 +1,8 @@
+import { OdsComponentMethods } from '../ods-component-methods';
+
+export interface OdsPaginationMethods extends OdsComponentMethods {
+  /**
+   * set page index on the component
+   */
+  setPageIndex(value: number): void;
+}

packages/libraries/core/src/components/pagination/ods-pagination-mock.ts

@@ -0,0 +1,22 @@
+import { OdsPagination } from './ods-pagination';
+import { OdsPaginationController } from './ods-pagination-controller';
+import { OdsPaginationEvents } from './ods-pagination-events';
+import { OdsPaginationMethods } from './ods-pagination-methods';
+import { OdsPaginationCurrentChangeEventDetail } from './ods-pagination-current-change-event-detail';
+
+export class OdsPaginationMock implements OdsPagination<OdsPaginationMethods, OdsPaginationEvents> {
+  disabled: boolean = false;
+  defaultCurrent?: number;
+  current: number = 1;
+  totalPages: number = 1;
+
+  odsCurrentChange!: OdsPaginationCurrentChangeEventDetail;
+
+  controller: OdsPaginationController = jest.fn() as unknown as OdsPaginationController;
+
+  setPageIndex = jest.fn();
+
+  onKeyup = jest.fn();
+
+  emitChange = jest.fn();
+}

packages/libraries/core/src/components/pagination/ods-pagination.ts

@@ -0,0 +1,17 @@
+import { OdsComponentGenericMethods } from '../ods-component-generic-methods';
+import { OdsComponentGenericEvents } from '../ods-component-generic-events';
+import { OdsComponent } from '../ods-component';
+import { OdsPaginationMethods } from './ods-pagination-methods';
+import { OdsPaginationEvents } from './ods-pagination-events';
+import { OdsPaginationAttributes } from './ods-pagination-attributes';
+import { OdsPaginationController } from './ods-pagination-controller';
+
+/**
+ * interface description of all implementation of `ods-pagination`.
+ * each implementation must have defined events, methods, attributes
+ * and one controller for the common behavior logic
+ */
+export type OdsPagination<
+  ComponentMethods extends OdsComponentGenericMethods<OdsPaginationMethods> = OdsComponentGenericMethods<OdsPaginationMethods>,
+  ComponentEvents extends OdsComponentGenericEvents<OdsPaginationEvents> = OdsComponentGenericEvents<OdsPaginationEvents>,
+> = OdsComponent<ComponentMethods, ComponentEvents, OdsPaginationAttributes, OdsPaginationController>;

packages/libraries/core/src/components/pagination/public-api.ts

@@ -0,0 +1,8 @@
+export * from './ods-pagination';
+export * from './ods-pagination-attributes';
+export * from './ods-pagination-controller';
+export * from './ods-pagination-default-attributes';
+export * from './ods-pagination-events';
+export * from './ods-pagination-methods';
+export * from './ods-pagination-current-change-event';
+export * from './ods-pagination-current-change-event-detail';

packages/libraries/core/src/components/public-api.ts

@@ -21,6 +21,7 @@ export * from './icon/public-api';
 export * from './input/public-api';
 export * from './link/public-api';
 export * from './location-tile/public-api';
+export * from './pagination/public-api';
 export * from './message/public-api';
 export * from './quantity/public-api';
 export * from './radio/public-api';

packages/libraries/testing/src/components/pagination/ods-pagination-base-attributes.ts

@@ -0,0 +1,11 @@
+import { OdsPaginationAttributes } from '@ovhcloud/ods-core';
+
+/**
+ * base attributes value of pagination
+ */
+export const odsPaginationBaseAttributes: OdsPaginationAttributes = {
+  disabled: false,
+  defaultCurrent: undefined,
+  current: 1,
+  totalPages: 1,
+};

packages/libraries/testing/src/components/pagination/public-api.ts

@@ -0,0 +1 @@
+export * from './ods-pagination-base-attributes';

packages/libraries/testing/src/components/public-api.ts

@@ -13,6 +13,7 @@ export * from './input/public-api';
 export * from './link/public-api';
 export * from './location-tile/public-api';
 export * from './message/public-api';
+export * from './pagination/public-api';
 export * from './quantity/public-api';
 export * from './radio/public-api';
 export * from './radio-button/public-api';

packages/specifications/components/pagination/specifications-pagination-contents.mdx

@@ -0,0 +1,3 @@
+| Name | Default | Description                          |
+| ---- | ------- | ------------------------------------ |
+| -    | 🚫      | pagination main content (by default) |

packages/specifications/components/pagination/specifications-pagination-events.mdx

@@ -0,0 +1,3 @@
+| Name               | type                                    | Description          |
+| ------------------ | --------------------------------------- | -------------------- |
+| `odsCurrentChange` | `OdsPaginationCurrentChangeEventDetail` | Current page changed |

packages/specifications/components/pagination/specifications-pagination-methods.mdx

@@ -0,0 +1,3 @@
+| Name           | Type   | Description        |
+| -------------- | ------ | ------------------ |
+| `setPageIndex` | `void` | Set Page pageindex |

packages/specifications/components/pagination/specifications-pagination-properties.mdx

@@ -0,0 +1,6 @@
+| Name               | Type      | default | Description                  |
+| ------------------ | --------- | ------- | ---------------------------- |
+| `[disabled]`       | `boolean` | `false` | Disabled state               |
+| `[currentDefault]` | `number`  | `''`    | Default curent selected page |
+| `[current]`        | `number`  | `'1'`   | The selected page            |
+| `[totalPages]`     | `number`  | `'1'`   | The total number of pages    |