feat(pagination): create the pagination component (VIV-964) (#1146)

* Create the pagination component

* Add readme to components.json

* Total and selectedIndex logics

* Selected index attribute

* Reset selected index

* Items 1 to 5 show now

* Creates the dots

* Clicking scenarios

* Need to fix RC between events in tests (clicked behaves wrongly)

* Test events complete

* Cleanup

* Completed the use cases

* Add documentation and navigation logic switch

* Add navIcons API

* Small change that ruins things :)

* Center dots

* pagination style :)

* Refactor the template

* Handle aria-pressed

* Tab works (need to test edge cases)

* Tab navigation complete

* Linting stuff

* Stylelint

* Added size API

* Hardened size API

* Add snapshots

* Update readme

chore(enums): fix size enums

* update snapshots

* Constant button width

* dots sizes & ui pngs

* remove only from test

* Remove obsolete branches

---------

Co-authored-by: RTannenbaum <[email protected]>

apps/docs/_data/components.json

@@ -426,5 +426,13 @@
 			"/assets/modules/components/tag-group/index.js",
 			"/assets/modules/components/tag/index.js"
 		]
+	},
+	{
+		"title": "pagination",
+		"status": "alpha",
+		"markdown": "./libs/components/src/lib/pagination/README.md",
+		"modules": [
+			"/assets/modules/components/pagination/index.js"
+		]
 	}
 ]

libs/components/src/lib/enums.ts

@@ -33,17 +33,17 @@ export enum Appearance {
 }
 
 export enum Size {
-	UltraCondensed = 'ultraCondensed',
-	SuperCondensed = 'superCondensed',
-	ExtraCondensed = 'extraCondensed',
-	SemiCondensed = 'semiCondensed',
+	UltraCondensed = 'ultra-condensed',
+	SuperCondensed = 'super-condensed',
+	ExtraCondensed = 'extra-condensed',
+	SemiCondensed = 'semi-condensed',
 	Condensed = 'condensed',
 	Normal = 'normal',
-	SemiExpanded = 'semiExpanded',
+	SemiExpanded = 'semi-expanded',
 	Expanded = 'expanded',
-	ExtraExpanded = 'extraExpanded',
-	SuperExpanded = 'superExpanded',
-	UltraExpanded = 'ultraExpanded',
+	ExtraExpanded = 'extra-expanded',
+	SuperExpanded = 'super-expanded',
+	UltraExpanded = 'ultra-expanded',
 }
 
 export enum LayoutSize {

libs/components/src/lib/pagination/README.md

@@ -0,0 +1,82 @@
+# pagination
+
+Represents a pagination custom element.
+
+```js
+<script type="module">import '@vonage/vivid/pagination';</script>
+```
+
+```html preview
+<vwc-pagination total="10"></vwc-pagination>
+```
+
+## Members
+
+### Total
+
+Set the `total` attribute to change the pagination's view total pages.
+
+- Type: `number`
+- Default: `0`
+
+```html preview
+<vwc-pagination total="20"></vwc-pagination>
+```
+
+### Size
+
+Set the `size` attribute to change the pagination's buttons sizes.
+
+- Type: `super-condensed` | `condensed` | `normal`
+- Default: `super-condensed`
+
+```html preview blocks
+<vwc-pagination size="super-condensed" total="20"></vwc-pagination>
+<vwc-pagination size="condensed" total="20"></vwc-pagination>
+<vwc-pagination size="normal" total="20"></vwc-pagination>
+```
+
+### Selected Index
+Set the `selectedIndex` attribute to change the pagination's currently selected index. Note that this is a Zero Index counter. It is set to -1 if total pages is 0.
+
+- Type: `number`
+- Default: `0`
+
+```html preview
+<vwc-pagination total="20"></vwc-pagination>
+<script>
+		pagination = document.querySelector('vwc-pagination');
+		pagination.selectedIndex = 5;
+</script>
+```
+
+### Nav Icons
+
+Set the `navIcons` attribute to change the pagination's navigation buttons type.
+
+- Type: `Boolean`
+- Default: `false`
+
+```html preview blocks
+<vwc-pagination total="20"></vwc-pagination>
+<vwc-pagination total="20" nav-icons></vwc-pagination>
+```
+
+### Pages List
+`pagesList` is an immutable array that represents the current pagination's state.
+
+## Events
+
+### vwc-pagination-change
+Listen to the `vwc-pagination-change` event to get notified when the pagination's state changes.
+
+```html preview
+<vwc-pagination total="20"></vwc-pagination>
+<div id="output"></div>
+<script>
+		pagination = document.querySelector('vwc-pagination');
+		pagination.addEventListener('vwc-pagination-change', (e) => {
+			document.querySelector('#output').innerHTML = JSON.stringify(e.detail);
+		});
+</script>
+```

libs/components/src/lib/pagination/definition.ts

@@ -0,0 +1,26 @@
+import type { FoundationElementDefinition } from '@microsoft/fast-foundation';
+import {buttonRegistries} from '../button/definition';
+import { registerFactory } from '../../shared/design-system';
+import styles from './pagination.scss';
+
+import { Pagination } from './pagination';
+import { PaginationTemplate as template } from './pagination.template';
+
+export const paginationDefinition =
+	Pagination.compose<FoundationElementDefinition>({
+		baseName: 'pagination',
+		template: template as any,
+		styles,
+	});
+
+/**
+ * @internal
+ */
+export const paginationRegistries = [paginationDefinition(), buttonRegistries];
+
+/**
+ * Registers the pagination element with the design system.
+ *
+ * @param prefix - the prefix to use for the component name
+ */
+export const registerPagination = registerFactory(paginationRegistries);

libs/components/src/lib/pagination/index.ts

@@ -0,0 +1,3 @@
+import { registerPagination } from './definition';
+
+registerPagination();

libs/components/src/lib/pagination/pagination.scss

@@ -0,0 +1,34 @@
+@use "../../../../../dist/libs/tokens/scss/tokens.constants" as constants;
+@use "../../../../../dist/libs/tokens/scss/size.variables" as size;
+
+
+.control{
+	display: inline-flex;
+	justify-content: space-between;
+}
+
+.buttons-wrapper {
+	display: flex;
+	column-gap: 4px;
+}
+
+.dots {
+	align-self: center;
+	text-align: center;
+
+	&:not(.size-super-condensed) {
+		font: var(#{constants.$vvd-typography-base-bold});
+	}
+	&.size-super-condensed {
+		font: var(#{constants.$vvd-typography-base-condensed-bold});
+		inline-size: #{size.$vvd-size-super-condensed};
+	}
+
+	&.size-condensed {
+		inline-size: #{size.$vvd-size-condensed};
+	}
+
+	&.size-normal {
+		inline-size: #{size.$vvd-size-normal};
+	}
+}