@startupjs-ui/pagination 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.1.3](https://github.com/startupjs/startupjs-ui/compare/v0.1.2...v0.1.3) (2025-12-29)
+
+**Note:** Version bump only for package @startupjs-ui/pagination
+
+
+
+
+
+## [0.1.2](https://github.com/startupjs/startupjs-ui/compare/v0.1.1...v0.1.2) (2025-12-29)
+
+
+### Features
+
+* add mdx and docs packages. Refactor docs to get rid of any @startupjs/ui usage and use startupjs-ui instead ([703c926](https://github.com/startupjs/startupjs-ui/commit/703c92636efb0421ffd11783f692fc892b74018f))
+* **pagination:** refactor Pagination component ([469d5f3](https://github.com/startupjs/startupjs-ui/commit/469d5f35b5d32122622a627d68832ec9a7b34729))

package/README.mdx

@@ -0,0 +1,165 @@
+import { useState } from 'react'
+import { $ } from 'startupjs'
+import { Sandbox } from '@startupjs-ui/docs'
+import Div from '@startupjs-ui/div'
+import Pagination, { _PropsJsonSchema as PaginationPropsJsonSchema } from './index'
+
+# Pagination
+
+The Pagination component enables the user to select a specific page from a range of pages.
+
+```jsx
+import { Pagination } from 'startupjs-ui'
+```
+
+## Simple example
+
+- `pages` specifies the total number of pages
+- `page` specifies the current page, starting from `0` to `pages - 1`
+
+```jsx example
+const [page, setPage] = useState(0)
+return (
+  <Div row align='center'>
+    <Pagination
+      page={page}
+      pages={10}
+      onChangePage={setPage}
+    />
+  </Div>
+)
+```
+
+## Alternatives
+
+- `count` - total count of items
+- `limit` - count of items to display per page
+- `skip` - count of items to skip
+
+You can use them instead of `pages` or `page` properties:
+
+- `count` and `limit` instead of `pages`
+- `limit` and `skip` instead of `page`
+
+```jsx example
+const COUNT = 100
+const LIMIT = 10
+const [skip, setSkip] = useState(0)
+return (
+  <Div row align='center'>
+    <Pagination
+      count={COUNT}
+      limit={LIMIT}
+      skip={skip}
+      onChangePage={(val) => setSkip(val * LIMIT)}
+    />
+  </Div>
+)
+```
+
+## Two-way data bindings
+
+You can use two-way data bindings `$page`, `$limit`, `$skip` instead of `page`, `limit`, `skip` respectively.
+
+```jsx example
+const $page = $(0)
+return (
+  <Div row align='center'>
+    <Pagination
+      $page={$page}
+      pages={10}
+    />
+  </Div>
+)
+```
+
+```jsx example
+const LIMIT = 10
+const $skip = $(0)
+return (
+  <Div row align='center'>
+    <Pagination
+      pages={10}
+      limit={LIMIT}
+      $skip={$skip}
+      onChangePage={(val) => $skip.set(val * LIMIT)}
+    />
+  </Div>
+)
+```
+
+## Buttons
+
+- `showPrevButton` displays the previous-page button, (default `true`)
+- `showNextButton` displays the next-page button (default `true`)
+- `showFirstButton` displays the first-page button (default `false`)
+- `showLastButton` displays the last-page button (default `false`)
+
+```jsx example
+const [page, setPage] = useState(0)
+return (
+  <Div row align='center'>
+    <Pagination
+      page={page}
+      pages={10}
+      showPrevButton={false}
+      showNextButton={false}
+      showFirstButton
+      showLastButton
+      onChangePage={setPage}
+    />
+  </Div>
+)
+```
+
+## Compact view
+
+To display the component in a compact view pass `variant='compact'`.
+
+```jsx example
+const [page, setPage] = useState(0)
+return (
+  <Div row align='center'>
+    <Pagination
+      variant='compact'
+      page={page}
+      pages={10}
+      onChangePage={setPage}
+    />
+  </Div>
+)
+```
+
+## Visible pages
+
+You can control the visibility of pages when component has default view (`variant='full'`).
+
+- `boundaryCount` controls the number of visible pages at the beginning and end
+- `siblingCount` controls the number of visible pages before and after the current page
+
+```jsx example
+const [page, setPage] = useState(5)
+return (
+  <Div row align='center'>
+    <Pagination
+      page={page}
+      boundaryCount={2}
+      siblingCount={0}
+      pages={10}
+      onChangePage={setPage}
+    />
+  </Div>
+)
+```
+
+## Sandbox
+
+<Sandbox
+  Component={Pagination}
+  propsJsonSchema={PaginationPropsJsonSchema}
+  props={{
+    page: $.session.Props.Pagination.page.get(),
+    onChangePage: page => $.session.Props.Pagination.page.set(page)
+  }}
+  $props={$.session.Props.Pagination}
+/>

package/index.cssx.styl

@@ -0,0 +1,21 @@
+.item
+  min-width 4u
+  height 4u
+  align-items center
+  justify-content center
+  padding-left 1u
+  padding-right @padding-left
+
+.page
+  &.selected
+    color var(--color-text-primary)
+
+.status
+  margin-left 1u
+  margin-right @margin-left
+
+.icon
+  color var(--color-text-secondary)
+
+  &.disabled
+    color var(--color-text-placeholder)

package/index.d.ts

@@ -0,0 +1,49 @@
+/* eslint-disable */
+// DO NOT MODIFY THIS FILE - IT IS AUTOMATICALLY GENERATED ON COMMITS.
+
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import './index.cssx.styl';
+declare const _default: React.ComponentType<PaginationProps>;
+export default _default;
+export declare const _PropsJsonSchema: {};
+export interface PaginationProps {
+    /** Custom styles applied to the root container */
+    style?: StyleProp<ViewStyle>;
+    /** Display variant controlling layout @default 'full' */
+    variant?: 'full' | 'compact';
+    /** Zero-based page index */
+    page?: number;
+    /** Scoped model for page index */
+    $page?: any;
+    /** Total number of pages */
+    pages?: number;
+    /** Number of items to skip before current page @default 0 */
+    skip?: number;
+    /** Scoped model for skip value */
+    $skip?: any;
+    /** Number of items per page @default 1 */
+    limit?: number;
+    /** Scoped model for limit value */
+    $limit?: any;
+    /** Total number of items @default 0 */
+    count?: number;
+    /** Visible pages at the start and end @default 1 */
+    boundaryCount?: number;
+    /** Visible sibling pages around the current page @default 1 */
+    siblingCount?: number;
+    /** Show button for the first page @default false */
+    showFirstButton?: boolean;
+    /** Show button for the last page @default false */
+    showLastButton?: boolean;
+    /** Show previous page button @default true */
+    showPrevButton?: boolean;
+    /** Show next page button @default true */
+    showNextButton?: boolean;
+    /** Disable all navigation @default false */
+    disabled?: boolean;
+    /** Called when the page changes */
+    onChangePage?: (page: number) => void;
+    /** Called when the page size changes */
+    onChangeLimit?: (limit: number) => void;
+}

package/index.tsx

@@ -0,0 +1,140 @@
+import React, { type ReactNode } from 'react'
+import { type StyleProp, type ViewStyle } from 'react-native'
+import { pug, observer } from 'startupjs'
+import { themed } from '@startupjs-ui/core'
+import Div from '@startupjs-ui/div'
+import Icon from '@startupjs-ui/icon'
+import Span from '@startupjs-ui/span'
+import { faAngleLeft } from '@fortawesome/free-solid-svg-icons/faAngleLeft'
+import { faAngleDoubleLeft } from '@fortawesome/free-solid-svg-icons/faAngleDoubleLeft'
+import { faAngleRight } from '@fortawesome/free-solid-svg-icons/faAngleRight'
+import { faAngleDoubleRight } from '@fortawesome/free-solid-svg-icons/faAngleDoubleRight'
+import usePagination from './usePagination'
+import './index.cssx.styl'
+
+const ICONS = {
+  first: faAngleDoubleLeft,
+  last: faAngleDoubleRight,
+  previous: faAngleLeft,
+  next: faAngleRight
+}
+
+export default observer(themed('Pagination', Pagination))
+
+export const _PropsJsonSchema = {/* PaginationProps */} // used in docs generation
+
+export interface PaginationProps {
+  /** Custom styles applied to the root container */
+  style?: StyleProp<ViewStyle>
+  /** Display variant controlling layout @default 'full' */
+  variant?: 'full' | 'compact'
+  /** Zero-based page index */
+  page?: number
+  /** Scoped model for page index */
+  $page?: any
+  /** Total number of pages */
+  pages?: number
+  /** Number of items to skip before current page @default 0 */
+  skip?: number
+  /** Scoped model for skip value */
+  $skip?: any
+  /** Number of items per page @default 1 */
+  limit?: number
+  /** Scoped model for limit value */
+  $limit?: any
+  /** Total number of items @default 0 */
+  count?: number
+  /** Visible pages at the start and end @default 1 */
+  boundaryCount?: number
+  /** Visible sibling pages around the current page @default 1 */
+  siblingCount?: number
+  /** Show button for the first page @default false */
+  showFirstButton?: boolean
+  /** Show button for the last page @default false */
+  showLastButton?: boolean
+  /** Show previous page button @default true */
+  showPrevButton?: boolean
+  /** Show next page button @default true */
+  showNextButton?: boolean
+  /** Disable all navigation @default false */
+  disabled?: boolean
+  /** Called when the page changes */
+  onChangePage?: (page: number) => void
+  /** Called when the page size changes */
+  onChangeLimit?: (limit: number) => void
+}
+
+function Pagination ({
+  style,
+  variant = 'full',
+  page,
+  $page,
+  pages,
+  skip = 0,
+  $skip,
+  limit = 1,
+  $limit,
+  count = 0,
+  boundaryCount = 1, // min 1
+  siblingCount = 1, // min 0
+  showFirstButton = false,
+  showLastButton = false,
+  showPrevButton = true,
+  showNextButton = true,
+  disabled = false,
+  onChangePage,
+  onChangeLimit
+}: PaginationProps): ReactNode {
+  const items = usePagination({
+    variant,
+    page,
+    $page,
+    pages,
+    skip,
+    $skip,
+    limit,
+    $limit,
+    count,
+    boundaryCount,
+    siblingCount,
+    showFirstButton,
+    showLastButton,
+    showPrevButton,
+    showNextButton,
+    disabled,
+    onChangePage,
+    onChangeLimit
+  })
+
+  return pug`
+    Div(row style=style)
+      each item, index in items
+        React.Fragment(key=index)
+          - const { type, value, selected, disabled, ...itemProps } = item
+          if type === 'page'
+            Div.item(
+              variant='highlight'
+              shape='circle'
+              disabled=disabled
+              ...itemProps
+            )
+              Span.page(styleName={ selected })= value + 1
+          else if ['first', 'last', 'previous', 'next'].includes(type)
+            Div.item(
+              variant='highlight'
+              shape='circle'
+              disabled=disabled
+              ...itemProps
+            )
+              Icon.icon(
+                styleName={disabled}
+                icon=ICONS[type]
+              )
+          else if ~type.indexOf('ellipsis')
+            Div.item
+              Span ...
+          else if type === 'status'
+            Div.status(vAlign='center' row)
+              Span= value
+    `
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@startupjs-ui/pagination",
+  "version": "0.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.tsx",
+  "types": "index.d.ts",
+  "type": "module",
+  "dependencies": {
+    "@startupjs-ui/core": "^0.1.3",
+    "@startupjs-ui/div": "^0.1.3",
+    "@startupjs-ui/icon": "^0.1.3",
+    "@startupjs-ui/span": "^0.1.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "startupjs": "*"
+  },
+  "gitHead": "fd964ebc3892d3dd0a6c85438c0af619cc50c3f0"
+}

package/usePagination.ts

@@ -0,0 +1,212 @@
+import { useBind } from 'startupjs'
+
+export interface UsePaginationProps {
+  variant?: 'full' | 'compact'
+  page?: number
+  $page?: any
+  pages?: number
+  skip?: number
+  $skip?: any
+  limit?: number
+  $limit?: any
+  count?: number
+  boundaryCount?: number
+  siblingCount?: number
+  showFirstButton?: boolean
+  showLastButton?: boolean
+  showPrevButton?: boolean
+  showNextButton?: boolean
+  disabled?: boolean
+  onChangePage?: (page: number) => void
+  onChangeLimit?: (limit: number) => void
+}
+
+type PaginationItemType =
+  | 'page'
+  | 'first'
+  | 'last'
+  | 'previous'
+  | 'next'
+  | 'status'
+  | 'start-ellipsis'
+  | 'end-ellipsis'
+
+interface PaginationItem {
+  onPress?: () => void
+  type: PaginationItemType
+  value: number | string | null
+  selected: boolean
+  disabled: boolean
+}
+
+export default function usePagination ({
+  variant,
+  page,
+  $page,
+  pages,
+  skip,
+  $skip,
+  limit,
+  $limit,
+  count,
+  boundaryCount = 1, // min 1
+  siblingCount = 1, // min 0
+  showFirstButton = false,
+  showLastButton = false,
+  showPrevButton = true,
+  showNextButton = true,
+  disabled,
+  onChangePage,
+  onChangeLimit
+}: UsePaginationProps): PaginationItem[] {
+  ({ page, onChangePage } = useBind({ $page, page, onChangePage }) as any)
+  ;({ skip } = useBind({ $skip, skip }) as any)
+  // TODO: Add selectbox to component to change limit
+  ;({ limit, onChangeLimit } = useBind({ $limit, limit, onChangeLimit }) as any)
+
+  if (page == null) {
+    if (skip != null && limit != null) {
+      page = Math.ceil(skip / limit)
+    } else {
+      throw new Error(
+        '[@startupjs/ui] usePagination: page cannot be calculated'
+      )
+    }
+  }
+
+  if (pages == null) {
+    if (count != null && limit != null) {
+      pages = Math.ceil(count / limit)
+    } else {
+      throw new Error(
+        '[@startupjs/ui] usePagination: pages cannot be calculated'
+      )
+    }
+  }
+
+  // min 1
+  const pagesCount = pages != null && pages > 0 ? pages : 1
+  const currentPage = page
+
+  // Basic list of items to render
+  const itemList: Array<PaginationItemType | number> = []
+
+  if (showFirstButton) itemList.push('first')
+  if (showPrevButton) itemList.push('previous')
+
+  if (variant === 'compact') {
+    itemList.push('status')
+  } else {
+    // this logic was taken from here
+    // https://github.com/mui-org/material-ui/blob/master/packages/material-ui-lab/src/Pagination/usePagination.js
+    const range = (start: number, end: number) => {
+      const length = end - start + 1
+      return Array.from({ length }, (_, i) => start + i)
+    }
+
+    const startPages = range(0, Math.min(boundaryCount, pagesCount) - 1)
+    const endPages = range(Math.max(pagesCount - boundaryCount, boundaryCount), pagesCount - 1)
+
+    const siblingsStart = Math.max(
+      Math.min(
+        // Natural start
+        currentPage - siblingCount,
+        // Lower boundary when page is high
+        pagesCount - boundaryCount - siblingCount * 2 - 2
+      ),
+      // Greater than startPages
+      boundaryCount + 1
+    )
+
+    const firstEndPage = endPages[0] ?? Number.NaN
+
+    const siblingsEnd = Math.min(
+      Math.max(
+        // Natural end
+        currentPage + siblingCount,
+        // Upper boundary when page is low
+        boundaryCount + siblingCount * 2 + 1
+      ),
+      // Less than endPages
+      firstEndPage - 2
+    )
+
+    itemList.push(...startPages)
+
+    // Start ellipsis
+    if (siblingsStart > boundaryCount + 1) {
+      itemList.push('start-ellipsis')
+    } else if (boundaryCount + 1 < pagesCount - boundaryCount) {
+      itemList.push(boundaryCount)
+    }
+
+    // Sibling pages
+    itemList.push(...range(siblingsStart, siblingsEnd))
+
+    // End ellipsis
+    if (siblingsEnd < pagesCount - boundaryCount - 2) {
+      itemList.push('end-ellipsis')
+    } else if (pagesCount - boundaryCount > boundaryCount) {
+      itemList.push(pagesCount - boundaryCount - 1)
+    }
+
+    itemList.push(...endPages)
+  }
+
+  if (showNextButton) itemList.push('next')
+  if (showLastButton) itemList.push('last')
+
+  // Map the button type to its page number
+  const buttonPage = (type: PaginationItemType): number | null => {
+    switch (type) {
+      case 'first':
+        return 0
+      case 'previous':
+        return currentPage - 1
+      case 'next':
+        return currentPage + 1
+      case 'last':
+        return pagesCount - 1
+      default:
+        return null
+    }
+  }
+
+  // Convert the basic item list to pagination item props objects
+  const items = itemList.map<PaginationItem>((item) => {
+    if (typeof item === 'number') {
+      return {
+        onPress: () => { onChangePage?.(item) },
+        type: 'page',
+        value: item,
+        selected: item === currentPage,
+        disabled: Boolean(disabled)
+      }
+    }
+
+    if (item === 'status') {
+      return {
+        type: item,
+        value: `${currentPage + 1} of ${pagesCount}`,
+        selected: false,
+        disabled: Boolean(disabled)
+      }
+    }
+
+    const value = buttonPage(item)
+    const isDisabled: boolean = disabled
+      ? true
+      : (!item.includes('ellipsis') &&
+          (item === 'next' || item === 'last' ? currentPage >= pagesCount - 1 : currentPage <= 0))
+
+    return {
+      onPress: () => { value !== null && onChangePage?.(value) },
+      type: item,
+      value,
+      selected: false,
+      disabled: isDisabled
+    }
+  })
+
+  return items
+}