Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): updates pagination docs to new format (VIV-2120) #2176

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(docs): updates pagination docs to new format (VIV-2120) #2176

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions apps/docs/content/_data/components.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -415,8 +415,13 @@
},
{
"title": "Pagination",
"page": "legacy",
"markdown": "./libs/components/src/lib/pagination/README.md"
"description": "Help users navigate forwards and backwards through a series of pages. For example, search results or guidance that’s divided into multiple pages.",
"variations": "./libs/components/src/lib/pagination/VARIATIONS.md",
"guidelines": "./libs/components/src/lib/pagination/GUIDELINES.md",
"hideGuidelines": "true",
"code": "./libs/components/src/lib/pagination/README.md",
"accessibility": "./libs/components/src/lib/pagination/ACCESSIBILITY.md",
"useCases": "./libs/components/src/lib/pagination/USE-CASES.md"
},
{
"title": "Empty State",
Expand Down
3 changes: 3 additions & 0 deletions libs/components/src/lib/pagination/ACCESSIBILITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
## Resources

- [Pagination: Manual accessibility test](https://docs.google.com/spreadsheets/d/19vZut40IcH_DSMQEd1v3Pryaj2zQy8Vi2-YNAGmig_0/edit?gid=1175911860#gid=1175911860)
103 changes: 103 additions & 0 deletions libs/components/src/lib/pagination/GUIDELINES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
## Labelling

### Label

<docs-do-dont>
<docs-do slot="description" headline="Use the label attribute whenever possible" caption="It provides a description of the purpose of the Number Field to all users and it is accessibly linked to the input element.">

```html preview example
<vwc-number-field label="Wanted quantity"></vwc-number-field>
```

</docs-do>
<docs-do dont headline="Don't use the placeholder attribute as a label">

```html preview example
<vwc-number-field placeholder="Wanted quantity"></vwc-number-field>
```

It's bad for UX and accessibility.<br />[The problem with placeholders](https://www.deque.com/blog/accessible-forms-the-problem-with-placeholders/)

</docs-do>
</docs-do-dont>

### Helper Text

<docs-do-dont>
<docs-do slot="description" headline="Use helper text to provide extra information about the field" caption="It is visible to the user at all times and it is read out by screen readers when the user focuses on the input element.">

```html preview example
<vwc-number-field
label="Wanted quantity"
helper-text="set a number higher than 1 less than 10"
></vwc-number-field>
```

</docs-do>
</docs-do-dont>

## Scale

<docs-do-dont headline="Use condensed Number Fields when space is limited" reverse>

<div slot="description">

The `condensed` Text Field is useful when used inside other components (inside [data-grid-cell](/components/data-grid/#cell) or [action-group](/components/action-group/) for a [toolbar](/components/button/use-cases/#toolbars)) as they take up less space.

</div>
<docs-do>

```html preview example
<div class="container">
<vwc-data-grid>
<vwc-data-grid-row row-type="header">
<vwc-data-grid-cell cell-type="columnheader">User</vwc-data-grid-cell>
<vwc-data-grid-cell
class="controls"
cell-type="columnheader"
></vwc-data-grid-cell>
</vwc-data-grid-row>
<vwc-data-grid-row>
<vwc-data-grid-cell>
<vwc-number-field label="Wanted quantity"></vwc-number-field>
</vwc-data-grid-cell>
<vwc-data-grid-cell class="controls">
<vwc-button
appearance="outlined"
size="condensed"
icon="edit-line"
aria-label="Edit"
></vwc-button>
<vwc-button
appearance="outlined"
size="condensed"
icon="delete-line"
aria-label="Delete"
connotation="alert"
></vwc-button>
</vwc-data-grid-cell>
</vwc-data-grid-row>
</vwc-data-grid>
</div>

<style>
.conainer {
display: block;
padding: 8px 0;
}

.controls {
width: 5.75rem;
}
</style>
```

</docs-do>
</docs-do-dont>

## Related Components

- [Text Area](/components/text-area/)
- [Text Field](/components/text-field)
- [Combobox](/components/combobox/)
- [Searchable Select](/components/searchable-select/)
115 changes: 38 additions & 77 deletions libs/components/src/lib/pagination/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,87 +1,65 @@
# Pagination
## Usage

The pagination component is used to navigate through a series of pages.
<vwc-tabs gutters="none">
<vwc-tab label="Web component"></vwc-tab>
<vwc-tab-panel>

```js
<script type="module">import '@vonage/vivid/pagination';</script>
import '@vonage/vivid/pagination';
```

```html preview
<vwc-pagination total="10"></vwc-pagination>
```

## Members

### Total
or, if you need to use a unique prefix:

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`
```js
import { registerPagination } from '@vonage/vivid';

```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>
registerPagination('your-prefix');
```

### Shape

Set the `shape` attribute to change the pagination's buttons shapes.

- Type: `rounded` | `pill`
- Default: `rounded`
```html preview
<script type="module">
import { registerPagination } from '@vonage/vivid';
registerPagination('your-prefix');
</script>

```html preview blocks
<vwc-pagination shape="rounded" total="20"></vwc-pagination>
<vwc-pagination shape="pill" total="20"></vwc-pagination>
<your-prefix-pagination total="10"></your-prefix-pagination>
```

### Selected Index

Set the `selected-index` attribute to change the pagination's currently selected index. Note that the value is zero-indexed. It is set to -1 if total pages is 0.
</vwc-tab-panel>
<vwc-tab label="Vue"></vwc-tab>
<vwc-tab-panel>

- Type: `number`
- Default: `0`
```html
<script setup lang="ts">
import { VPagination } from '@vonage/vivid-vue';
</script>

```html preview
<vwc-pagination total="20" selected-index="5"></vwc-pagination>
<template>
<VPagination total="10" />
</template>
```

### Nav Icons

Set the `nav-icons` attribute to change the pagination's navigation buttons type.

- Type: `Boolean`
- Default: `false`
</vwc-tab-panel>
</vwc-tabs>

```html preview blocks
<vwc-pagination total="20"></vwc-pagination>
<vwc-pagination total="20" nav-icons></vwc-pagination>
```
## API Reference

## Properties
### Properties

<div class="table-wrapper">

| Name | Type | Default | Description |
| ----------- | ---------- | ------- | ------------------------------------------------------------------ |
| `pagesList` | `number[]` | `[]` | An immutable array that represents the current pagination's state. |
| Name | Type | Description |
| ---------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
| `nav-icons` | `boolean` | Changes the Previous and Next buttons to chevron icons |
| `pagesList` | `number[]` | An immutable array that represents the current pagination's state |
| `selected-index` | `number` | Index of the currently selected page |
| `shape` | `rounded` (default), `pill` | Sets the shapes of the navigation buttons |
| `size` | `super-condensed` (default), `condensed`, `normal` | Sets the size of the navigation buttons |
| `total` | `number` | Total number of pages to navigate |

</div>

## Events
### Events

<div class="table-wrapper">

Expand All @@ -90,20 +68,3 @@ Set the `nav-icons` attribute to change the pagination's navigation buttons type
| `pagination-change` | `CustomEvent<{selectedIndex: number, total: number, oldIndex: number}>` | Yes | Yes | Fires when the page changes. |

</div>

## Use Cases

### With border

```html preview
<style>
vwc-pagination#outlined {
border: 1px solid var(--vvd-color-neutral-400);
padding: 6px;
border-radius: 24px;
display: inline-block;
}
</style>

<vwc-pagination id="outlined" total="10" shape="pill"></vwc-pagination>
```
14 changes: 14 additions & 0 deletions libs/components/src/lib/pagination/USE-CASES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
## With border

```html preview
<vwc-pagination class="outlined" total="10" shape="pill"></vwc-pagination>

<style>
.outlined {
border: 1px solid var(--vvd-color-neutral-400);
padding: 6px;
border-radius: 24px;
display: inline-block;
}
</style>
```
49 changes: 49 additions & 0 deletions libs/components/src/lib/pagination/VARIATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
## Total

The `total` attribute sets the total amount of pages. If set to `0` (it's default value) both 'Previous' and 'Next' links will be disabled.

```html preview
<vwc-pagination total="20"></vwc-pagination>
```

## Selected Index

The `selected-index` attribute sets the currently selected page.

Note that the value is zero-indexed. It is set to `-1` if total pages is `0`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this can be an info note :)


```html preview
<vwc-pagination total="20" selected-index="5"></vwc-pagination>
```

## Size

The `size` attribute sets the pagination's buttons sizes.

```html preview
<p>super-condensed (default)</p>
<vwc-pagination size="super-condensed" total="20"></vwc-pagination>
<p>condensed</p>
<vwc-pagination size="condensed" total="20"></vwc-pagination>
<p>normal</p>
<vwc-pagination size="normal" total="20"></vwc-pagination>
```

## Shape

The `shape` attribute sets the pagination's buttons shapes.

```html preview
<p>rounded (default)</p>
<vwc-pagination shape="rounded" total="20"></vwc-pagination>
<p>pill</p>
<vwc-pagination shape="pill" total="20"></vwc-pagination>
```

## Nav Icons

The `nav-icons` attribute changes the pagination's "Previous" and "Next" buttons to be chevron icons.

```html preview
<vwc-pagination total="20" nav-icons selected-index="2"></vwc-pagination>
```
45 changes: 36 additions & 9 deletions libs/components/src/lib/pagination/ui.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,49 @@
import * as path from 'path';
import { expect, test } from '@playwright/test';
import type { Page } from '@playwright/test';
import {
extractHTMLBlocksFromReadme,
loadComponents,
loadTemplate,
} from '../../visual-tests/visual-tests-utils.js';

const components = ['pagination'];

test('should show the component', async ({ page }: { page: Page }) => {
const template = extractHTMLBlocksFromReadme(
path.join(new URL('.', import.meta.url).pathname, 'README.md')
).reduce(
(htmlString: string, block: string) =>
`${htmlString} <div style="margin: 5px;">${block}</div>`,
''
);
const template = `
<div style="margin: 5px;">
<vwc-pagination total="10"></vwc-pagination>
</div>
<div style="margin: 5px;">
<vwc-pagination total="20"></vwc-pagination>
</div>
<div style="margin: 5px;">
<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>
</div>
<div style="margin: 5px;">
<vwc-pagination shape="rounded" total="20"></vwc-pagination>
<vwc-pagination shape="pill" total="20"></vwc-pagination>
</div>
<div style="margin: 5px;">
<vwc-pagination total="20" selected-index="5"></vwc-pagination>
</div>
<div style="margin: 5px;">
<vwc-pagination total="20"></vwc-pagination>
<vwc-pagination total="20" nav-icons></vwc-pagination>
</div>
<div style="margin: 5px;">
<style>
vwc-pagination#outlined {
border: 1px solid var(--vvd-color-neutral-400);
padding: 6px;
border-radius: 24px;
display: inline-block;
}
</style>

<vwc-pagination id="outlined" total="10" shape="pill"></vwc-pagination>
</div>
`;

await loadComponents({
page,
Expand Down
Loading