feat(Pagination): new component (#257)

Co-authored-by: Benjamin Canac <canacb1@gmail.com>
Co-authored-by: Haytham A. Salama <haythamasalama@gmail.com>

docs/components/content/ComponentCard.vue

@@ -121,7 +121,7 @@ const meta = await fetchComponentMeta(name)
 // eslint-disable-next-line vue/no-dupe-keys
 const ui = computed(() => ({ ...appConfig.ui[camelName], ...props.ui }))
 
-const fullProps = computed(() => ({ ...props.baseProps, ...componentProps }))
+const fullProps = computed(() => ({ ...baseProps, ...componentProps }))
 const vModel = computed({
   get: () => baseProps.modelValue,
   set: (value) => {

docs/components/content/examples/PaginationExampleBasic.vue

@@ -0,0 +1,8 @@
+<script setup>
+const page = ref(1)
+const items = ref(Array(55))
+</script>
+
+<template>
+  <UPagination v-model="page" :page-count="5" :total="items.length" />
+</template>

docs/components/content/examples/PaginationExamplePrevNextSlots.vue

@@ -0,0 +1,20 @@
+<script setup>
+const page = ref(1)
+const items = ref(Array(55))
+</script>
+
+<template>
+  <UPagination v-model="page" :total="items.length" :ui="{ rounded: 'first-of-type:rounded-l-md last-of-type:rounded-r-md' }">
+    <template #prev="{ onClick }">
+      <UTooltip text="Previous page">
+        <UButton icon="i-heroicons-arrow-small-left-20-solid" color="primary" :ui="{ rounded: 'rounded-full' }" class="mr-2" @click="onClick" />
+      </UTooltip>
+    </template>
+
+    <template #next="{ onClick }">
+      <UTooltip text="Next page">
+        <UButton icon="i-heroicons-arrow-small-right-20-solid" color="primary" :ui="{ rounded: 'rounded-full' }" class="ml-2" @click="onClick" />
+      </UTooltip>
+    </template>
+  </UPagination>
+</template>

docs/components/content/examples/TableExamplePaginable.vue

@@ -0,0 +1,98 @@
+<script setup>
+const people = [{
+  id: 1,
+  name: 'Lindsay Walton',
+  title: 'Front-end Developer',
+  email: 'lindsay.walton@example.com',
+  role: 'Member'
+}, {
+  id: 2,
+  name: 'Courtney Henry',
+  title: 'Designer',
+  email: 'courtney.henry@example.com',
+  role: 'Admin'
+}, {
+  id: 3,
+  name: 'Tom Cook',
+  title: 'Director of Product',
+  email: 'tom.cook@example.com',
+  role: 'Member'
+}, {
+  id: 4,
+  name: 'Whitney Francis',
+  title: 'Copywriter',
+  email: 'whitney.francis@example.com',
+  role: 'Admin'
+}, {
+  id: 5,
+  name: 'Leonard Krasner',
+  title: 'Senior Designer',
+  email: 'leonard.krasner@example.com',
+  role: 'Owner'
+}, {
+  id: 6,
+  name: 'Floyd Miles',
+  title: 'Principal Designer',
+  email: 'floyd.miles@example.com',
+  role: 'Member'
+}, {
+  id: 7,
+  name: 'Emily Selman',
+  title: 'VP, User Experience',
+  email: '',
+  role: 'Admin'
+}, {
+  id: 8,
+  name: 'Kristin Watson',
+  title: 'VP, Human Resources',
+  email: '',
+  role: 'Member'
+}, {
+  id: 9,
+  name: 'Emma Watson',
+  title: 'Front-end Developer',
+  email: '',
+  role: 'Member'
+}, {
+  id: 10,
+  name: 'John Doe',
+  title: 'Designer',
+  email: '',
+  role: 'Admin'
+}, {
+  id: 11,
+  name: 'Jane Doe',
+  title: 'Director of Product',
+  email: '',
+  role: 'Member'
+}, {
+  id: 12,
+  name: 'John Smith',
+  title: 'Copywriter',
+  email: '',
+  role: 'Admin'
+}, {
+  id: 13,
+  name: 'Jane Smith',
+  title: 'Senior Designer',
+  email: '',
+  role: 'Owner'
+}]
+
+const page = ref(1)
+const pageCount = 5
+
+const rows = computed(() => {
+  return people.slice((page.value - 1) * pageCount, (page.value) * pageCount)
+})
+</script>
+
+<template>
+  <div>
+    <UTable :rows="rows" />
+
+    <div class="flex justify-end px-3 py-3.5 border-t border-gray-200 dark:border-gray-700">
+      <UPagination v-model="page" :page-count="pageCount" :total="people.length" />
+    </div>
+  </div>
+</template>

docs/components/content/themes/PaginationThemeRounded.vue

@@ -0,0 +1,21 @@
+<script setup>
+const page = ref(1)
+const items = ref(Array(55))
+</script>
+
+<template>
+  <UPagination
+    v-model="page"
+    :total="items.length"
+    :ui="{
+      wrapper: 'flex items-center gap-1',
+      rounded: 'rounded-full min-w-[32px] justify-center'
+    }"
+    :prev-button="null"
+    :next-button="{
+      icon: 'i-heroicons-arrow-small-right-20-solid',
+      color: 'primary',
+      variant: 'outline'
+    }"
+  />
+</template>

docs/content/4.data/1.table.md

@@ -366,6 +366,41 @@ const filteredRows = computed(() => {
 ```
 ::
 
+### Paginable
+
+You can easily use the [Pagination](/navigation/pagination) component to paginate the rows.
+
+::component-example
+---
+padding: false
+---
+
+#default
+:table-example-paginable{class="w-full"}
+
+#code
+```vue
+<script setup>
+const people = [...]
+
+const page = ref(1)
+const pageCount = 5
+
+const rows = computed(() => {
+  return people.slice((page.value - 1) * pageCount, (page.value) * pageCount)
+})
+</script>
+
+<template>
+  <div>
+    <UTable :rows="rows" />
+
+    <UPagination v-model="page" :page-count="pageCount" :total="people.length" />
+  </div>
+</template>
+```
+::
+
 ### Empty
 
 Use the `empty-state` prop to display a message when there are no results.

docs/content/5.navigation/1.vertical-navigation.md

@@ -39,11 +39,9 @@ const links = [{
 ```
 ::
 
-## Themes
+## Theme
 
-Our theming system provides a lot of flexibility to customize the component. Here is some examples of what you can do.
+Our theming system provides a lot of flexibility to customize the component. Here is an example of what you can do.
-
-### Tailwind
 
 ::component-example
 #default

docs/content/5.navigation/3.pagination.md

@@ -0,0 +1,186 @@
+---
+github: true
+description: Add a pagination to handle pages.
+---
+
+## Usage
+
+Use a `v-model` to get a reactive page alongside a `total` which represents the total of items. You can also use the `page-count` prop to define the number of items per page which defaults to `10`.
+
+::component-example
+#default
+:pagination-example-basic
+
+#code
+```vue
+<script setup>
+const page = ref(1)
+const items = ref(Array(55))
+</script>
+
+<template>
+  <UPagination v-model="page" :page-count="5" :total="items.length" />
+</template>
+```
+::
+
+### Max
+
+Use the `max` prop to set a maximum of displayed pages. Defaults to `7`, being the minimum.
+
+::component-card
+---
+baseProps:
+  modelValue: 1
+props:
+  max: 5
+  pageCount: 5
+  total: 100
+excludedProps:
+  - pageCount
+  - total
+---
+::
+
+### Size
+
+Use the `size` prop to change the size of the buttons.
+
+::component-card
+---
+baseProps:
+  modelValue: 1
+  total: 100
+props:
+  size: 'sm'
+ui:
+  size:
+    2xs: true
+    xs: true
+    sm: true
+    md: true
+    lg: true
+    xl: true
+---
+::
+
+### Active / Inactive
+
+Use the `active-button` and `inactive-button` props to customize the active and inactive buttons of the Pagination.
+
+::component-card
+---
+baseProps:
+  modelValue: 1
+  total: 100
+props:
+  activeButton:
+    variant: 'outline'
+  inactiveButton:
+    color: 'gray'
+excludedProps:
+  - activeButton
+  - inactiveButton
+---
+::
+
+### Prev / Next
+
+Use the `prev-button` and `next-button` props to customize the prev and next buttons of the Pagination.
+
+::component-card
+---
+baseProps:
+  modelValue: 1
+  total: 100
+props:
+  prevButton:
+    icon: 'i-heroicons-arrow-small-left-20-solid'
+    label: Prev
+    color: 'gray'
+  nextButton:
+    icon: 'i-heroicons-arrow-small-right-20-solid'
+    trailing: true
+    label: Next
+    color: 'gray'
+excludedProps:
+  - prevButton
+  - nextButton
+---
+::
+
+## Theme
+
+Our theming system provides a lot of flexibility to customize the component. Here is an example of what you can do.
+
+::component-example
+#default
+:pagination-theme-rounded
+#code
+```vue
+<script setup>
+const page = ref(1)
+const items = ref(Array(55))
+</script>
+
+<template>
+  <UPagination
+    v-model="page"
+    :total="items.length"
+    :ui="{
+      wrapper: 'flex items-center gap-1',
+      rounded: 'rounded-full min-w-[32px] justify-center'
+    }"
+    :prev-button="null"
+    :next-button="{
+      icon: 'i-heroicons-arrow-small-right-20-solid',
+      color: 'primary',
+      variant: 'outline'
+    }"
+  />
+</template>
+```
+::
+
+## Slots
+
+### `prev` / `next`
+
+Use the `#prev` and `#next` slots to set the content of the previous and next buttons.
+
+::component-example
+#default
+:pagination-example-prev-next-slots
+
+#code
+```vue
+<script setup>
+const page = ref(1);
+const items = ref(Array(55));
+</script>
+
+<template>
+  <UPagination v-model="page" :total="items.length" :ui="{ rounded: 'first-of-type:rounded-l-md last-of-type:rounded-r-md' }">
+    <template #prev="{ onClick }">
+      <UTooltip text="Previous page">
+        <UButton icon="i-heroicons-arrow-small-left-20-solid" color="primary" :ui="{ rounded: 'rounded-full' }" class="mr-2" @click="onClick" />
+      </UTooltip>
+    </template>
+
+    <template #next="{ onClick }">
+      <UTooltip text="Next page">
+        <UButton icon="i-heroicons-arrow-small-right-20-solid" color="primary" :ui="{ rounded: 'rounded-full' }" class="ml-2" @click="onClick" />
+      </UTooltip>
+    </template>
+  </UPagination>
+</template>
+```
+::
+
+## Props
+
+:component-props
+
+## Preset
+
+:component-preset

src/runtime/app.config.ts

@@ -634,6 +634,29 @@ const commandPalette = {
   }
 }
 
+const pagination = {
+  wrapper: 'flex items-center -space-x-px',
+  base: '',
+  rounded: 'first:rounded-l-md last:rounded-r-md',
+  default: {
+    size: 'sm',
+    activeButton: {
+      color: 'primary'
+    },
+    inactiveButton: {
+      color: 'white'
+    },
+    prevButton: {
+      color: 'white',
+      icon: 'i-heroicons-chevron-left-20-solid'
+    },
+    nextButton: {
+      color: 'white',
+      icon: 'i-heroicons-chevron-right-20-solid'
+    }
+  }
+}
+
 // Overlays
 
 const modal = {
@@ -841,6 +864,7 @@ export default {
     skeleton,
     verticalNavigation,
     commandPalette,
+    pagination,
     modal,
     slideover,
     popover,

src/runtime/components/navigation/Pagination.vue

@@ -0,0 +1,218 @@
+<template>
+  <div :class="ui.wrapper">
+    <slot name="prev" :on-click="onClickPrev">
+      <UButton
+        v-if="prevButton"
+        :size="size"
+        :disabled="!canGoPrev"
+        :class="[ui.base, ui.rounded]"
+        v-bind="{ ...ui.default.prevButton, ...prevButton }"
+        :ui="{ rounded: '' }"
+        @click="onClickPrev"
+      />
+    </slot>
+
+    <UButton
+      v-for="(page, index) of displayedPages"
+      :key="index"
+      :size="size"
+      :label="`${page}`"
+      v-bind="page === currentPage ? { ...ui.default.activeButton, ...activeButton } : { ...ui.default.inactiveButton, ...inactiveButton }"
+      :class="[{ 'pointer-events-none': typeof page === 'string', 'z-[1]': page === currentPage }, ui.base, ui.rounded]"
+      :ui="{ rounded: '' }"
+      @click="() => onClickPage(page)"
+    />
+
+    <slot name="next" :on-click="onClickNext">
+      <UButton
+        v-if="nextButton"
+        :size="size"
+        :disabled="!canGoNext"
+        :class="[ui.base, ui.rounded]"
+        v-bind="{ ...ui.default.nextButton, ...nextButton }"
+        :ui="{ rounded: '' }"
+        @click="onClickNext"
+      />
+    </slot>
+  </div>
+</template>
+
+<script lang="ts">
+import { computed, defineComponent } from 'vue'
+import type { PropType } from 'vue'
+import { defu } from 'defu'
+import UButton from '../elements/Button.vue'
+import type { Button } from '../../types/button'
+import { useAppConfig } from '#imports'
+// TODO: Remove
+// @ts-expect-error
+import appConfig from '#build/app.config'
+
+// const appConfig = useAppConfig()
+
+export default defineComponent({
+  components: {
+    UButton
+  },
+  props: {
+    modelValue: {
+      type: Number,
+      required: true
+    },
+    pageCount: {
+      type: Number,
+      default: 10
+    },
+    total: {
+      type: Number,
+      required: true
+    },
+    max: {
+      type: Number,
+      default: 7,
+      validate (value) {
+        return value >= 7 && value < Number.MAX_VALUE
+      }
+    },
+    size: {
+      type: String,
+      default: () => appConfig.ui.pagination.default.size,
+      validator (value: string) {
+        return Object.keys(appConfig.ui.button.size).includes(value)
+      }
+    },
+    activeButton: {
+      type: Object as PropType<Partial<Button>>,
+      default: () => appConfig.ui.pagination.default.activeButton
+    },
+    inactiveButton: {
+      type: Object as PropType<Partial<Button>>,
+      default: () => appConfig.ui.pagination.default.inactiveButton
+    },
+    prevButton: {
+      type: Object as PropType<Partial<Button>>,
+      default: () => appConfig.ui.pagination.default.prevButton
+    },
+    nextButton: {
+      type: Object as PropType<Partial<Button>>,
+      default: () => appConfig.ui.pagination.default.nextButton
+    },
+    divider: {
+      type: String,
+      default: '…'
+    },
+    ui: {
+      type: Object as PropType<Partial<typeof appConfig.ui.pagination>>,
+      default: () => appConfig.ui.pagination
+    }
+  },
+  emits: ['update:modelValue'],
+  setup (props, { emit }) {
+    // TODO: Remove
+    const appConfig = useAppConfig()
+
+    const ui = computed<Partial<typeof appConfig.ui.pagination>>(() => defu({}, props.ui, appConfig.ui.pagination))
+
+    const currentPage = computed({
+      get () {
+        return props.modelValue
+      },
+      set (value) {
+        emit('update:modelValue', value)
+      }
+    })
+
+    const pages = computed(() => Array.from({ length: Math.ceil(props.total / props.pageCount) }, (_, i) => i + 1))
+
+    const displayedPages = computed(() => {
+      if (!props.max || pages.value.length <= 5) {
+        return pages.value
+      } else {
+        const current = currentPage.value
+        const max = pages.value.length
+        const r = Math.floor((Math.min(props.max, max) - 5) / 2)
+        const r1 = current - r
+        const r2 = current + r
+        const beforeWrapped = r1 - 1 > 1
+        const afterWrapped = r2 + 1 < max
+        const items: Array<number | string> = [1]
+
+        if (beforeWrapped) items.push(props.divider)
+
+        if (!afterWrapped) {
+          const addedItems = (current + r + 2) - max
+          for (let i = current - r - addedItems; i <= current - r - 1; i++) {
+            items.push(i)
+          }
+        }
+
+        for (let i = r1 > 2 ? (r1) : 2; i <= Math.min(max, r2); i++) {
+          items.push(i)
+        }
+
+        if (!beforeWrapped) {
+          const addedItems = 1 - (current - r - 2)
+          for (let i = current + r + 1; i <= current + r + addedItems; i++) {
+            items.push(i)
+          }
+        }
+
+        if (afterWrapped) items.push(props.divider)
+
+        if (r2 < max) items.push(max)
+
+        // Replace divider by number on start edge case [1, '…', 3, ...]
+        if (items.length >= 3 && items[1] === props.divider && items[2] === 3) {
+          items[1] = 2
+        }
+        // Replace divider by number on end edge case [..., 48, '…', 50]
+        if (items.length >= 3 && items[items.length - 2] === props.divider && items[items.length - 1] === items.length) {
+          items[items.length - 2] = items.length - 1
+        }
+
+        return items
+      }
+    })
+
+    const canGoPrev = computed(() => currentPage.value > 1)
+    const canGoNext = computed(() => currentPage.value < pages.value.length)
+
+    function onClickPage (page: number | string) {
+      if (typeof page === 'string') {
+        return
+      }
+
+      currentPage.value = page
+    }
+
+    function onClickPrev () {
+      if (!canGoPrev.value) {
+        return
+      }
+
+      currentPage.value--
+    }
+
+    function onClickNext () {
+      if (!canGoNext.value) {
+        return
+      }
+
+      currentPage.value++
+    }
+
+    return {
+      // eslint-disable-next-line vue/no-dupe-keys
+      ui,
+      currentPage,
+      pages,
+      displayedPages,
+      canGoPrev,
+      canGoNext,
+      onClickPrev,
+      onClickNext,
+      onClickPage
+    }
+  }
+})
+</script>

src/runtime/utils/index.ts

@@ -18,14 +18,18 @@ export const omit = (obj: object, keys: string[]) => {
 export const getSlotsChildren = (slots: any) => {
   let children = slots.default?.()
   if (children.length) {
-    if (typeof children[0].type === 'symbol') {
+    children = children.flatMap(c => {
-      // @ts-ignore-next
+      if (typeof c.type === 'symbol') {
-      children = children[0].children
+        if (typeof c.children === 'string') {
-      // @ts-ignore-next
+          // `v-if="false"` or commented node
-    } else if (children[0].type.name === 'ContentSlot') {
+          return
-      // @ts-ignore-next
+        }
-      children = children[0].ctx.slots.default?.()
+        return c.children
-    }
+      } else if (c.type.name === 'ContentSlot') {
+        return c.ctx.slots.default?.()
+      }
+      return c
+    }).filter(Boolean)
   }
   return children
 }