@instructure/ui-pagination 8.51.0 → 8.51.1-snapshot-6

package/lib/Pagination/index.js

@@ -62,7 +62,8 @@ const childrenArray = props => {
   return Array.isArray(children) ? children : [children];
 };
 function propsHaveCompactView(props) {
-  return props.variant === 'compact' && childrenArray(props).length > 5;
+  if (props.children) return props.variant === 'compact' && childrenArray(props).length > 5;
+  return props.variant === 'compact' && props.totalPageNumber > 5;
 }
 /**
 ---
@@ -78,6 +79,7 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
     this._nextButton = null;
     this._lastButton = null;
     this.ref = null;
+    this.currentPageRef = null;
     this.handleElementRef = el => {
       this.ref = el;
       if (el && typeof this.props.elementRef === 'function') {
@@ -89,6 +91,114 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
         this.props.inputRef(el);
       }
     };
+    this.renderDefaultPageInput = () => {
+      const _this$props = this.props,
+        currentPage = _this$props.currentPage,
+        totalPageNumber = _this$props.totalPageNumber;
+      return (0, _emotion.jsx)(_PaginationPageInput.PaginationPageInput, {
+        numberOfPages: totalPageNumber,
+        currentPageIndex: currentPage - 1,
+        onChange: (_e, nextPageIndex) => {
+          var _this$props$onPageCha, _this$props2;
+          return (_this$props$onPageCha = (_this$props2 = this.props).onPageChange) === null || _this$props$onPageCha === void 0 ? void 0 : _this$props$onPageCha.call(_this$props2, nextPageIndex + 1, currentPage);
+        },
+        screenReaderLabel: this.props.screenReaderLabelNumberInput,
+        label: this.props.labelNumberInput,
+        disabled: this.props.disabled,
+        inputRef: this.handleInputRef
+      });
+    };
+    this.handleNavigation = (nextIndex, previousIndex) => {
+      const onPageChange = this.props.onPageChange;
+      if (typeof onPageChange === 'function') {
+        onPageChange(nextIndex, previousIndex);
+      }
+    };
+    this.renderPagesInInterval = (from, to, currentPage) => {
+      if (to - from > 1000) throw new Error('Pagination: too many pages (more than 1000)');
+      const pages = [];
+      for (let i = from; i <= to; i++) {
+        var _this$props$renderPag, _this$props3;
+        pages.push((0, _emotion.jsx)(Pagination.Page, {
+          ref: e => i === currentPage ? this.currentPageRef = e : null,
+          key: i,
+          onClick: () => this.handleNavigation(i, currentPage),
+          current: i === currentPage
+        }, (_this$props$renderPag = (_this$props3 = this.props).renderPageIndicator) === null || _this$props$renderPag === void 0 ? void 0 : _this$props$renderPag.call(_this$props3, i, currentPage)));
+      }
+      return pages;
+    };
+    this.renderDefaultPages = () => {
+      const _this$props4 = this.props,
+        ellipsis = _this$props4.ellipsis,
+        currentPage = _this$props4.currentPage,
+        totalPageNumber = _this$props4.totalPageNumber,
+        siblingCount = _this$props4.siblingCount,
+        boundaryCount = _this$props4.boundaryCount,
+        variant = _this$props4.variant;
+      const pages = [];
+      if (totalPageNumber <= 2 * boundaryCount || totalPageNumber <= 1 + siblingCount + boundaryCount || variant === 'full') {
+        return this.renderPagesInInterval(1, totalPageNumber, currentPage);
+      }
+      if (currentPage > boundaryCount + siblingCount + 1) {
+        pages.push(this.renderPagesInInterval(1, boundaryCount, currentPage));
+        pages.push(ellipsis);
+        if (currentPage - siblingCount > totalPageNumber - boundaryCount + 1) {
+          pages.push(this.renderPagesInInterval(totalPageNumber - boundaryCount + 1, totalPageNumber, currentPage));
+          return pages;
+        }
+        pages.push(this.renderPagesInInterval(currentPage - siblingCount, currentPage, currentPage));
+      } else {
+        pages.push(this.renderPagesInInterval(1, Math.max(currentPage, boundaryCount), currentPage));
+      }
+      if (currentPage < totalPageNumber - (siblingCount + boundaryCount)) {
+        pages.push(this.renderPagesInInterval(Math.max(currentPage, boundaryCount) + 1, currentPage + siblingCount, currentPage));
+        pages.push(ellipsis);
+        pages.push(this.renderPagesInInterval(totalPageNumber - boundaryCount + 1, totalPageNumber, currentPage));
+      } else {
+        pages.push(this.renderPagesInInterval(currentPage + 1, totalPageNumber, currentPage));
+      }
+      return pages;
+    };
+    this.renderDefaultArrowButton = direction => {
+      if (!this.withFirstAndLastButton && (direction === 'first' || direction === 'last')) {
+        return null;
+      }
+      // We don't display the arrows in "compact" variant under 6 items
+      if (!(propsHaveCompactView(this.props) || this.inputMode)) {
+        return null;
+      }
+      const _this$props5 = this.props,
+        totalPageNumber = _this$props5.totalPageNumber,
+        currentPage = _this$props5.currentPage;
+      const _this$getArrowVariant = this.getArrowVariant(direction, currentPage - 1, totalPageNumber),
+        label = _this$getArrowVariant.label,
+        shouldEnableIcon = _this$getArrowVariant.shouldEnableIcon,
+        handleButtonRef = _this$getArrowVariant.handleButtonRef;
+      const disabled = this.props.disabled || !shouldEnableIcon;
+      const onClick = () => {
+        if (direction === 'first') {
+          this.handleNavigation(1, currentPage);
+        }
+        if (direction === 'prev') {
+          this.handleNavigation(Math.max(currentPage - 1, 1), currentPage);
+        }
+        if (direction === 'next') {
+          this.handleNavigation(Math.min(currentPage + 1, totalPageNumber), currentPage);
+        }
+        if (direction === 'last') {
+          this.handleNavigation(totalPageNumber, currentPage);
+        }
+      };
+      return shouldEnableIcon || this.showDisabledButtons ? (0, _emotion.jsx)(_PaginationArrowButton.PaginationArrowButton, {
+        direction: direction,
+        "data-direction": direction,
+        label: label,
+        onClick: onClick,
+        disabled: disabled,
+        buttonRef: handleButtonRef
+      }) : null;
+    };
     this._labelId = props.deterministicId();
   }
   get _root() {
@@ -119,12 +229,19 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
     }
   }
   componentDidMount() {
-    var _this$props$makeStyle, _this$props;
-    (_this$props$makeStyle = (_this$props = this.props).makeStyles) === null || _this$props$makeStyle === void 0 ? void 0 : _this$props$makeStyle.call(_this$props);
+    var _this$props$makeStyle, _this$props6;
+    (_this$props$makeStyle = (_this$props6 = this.props).makeStyles) === null || _this$props$makeStyle === void 0 ? void 0 : _this$props$makeStyle.call(_this$props6);
   }
   componentDidUpdate(prevProps, _prevState, snapshot) {
-    var _this$props$makeStyle2, _this$props2;
-    (_this$props$makeStyle2 = (_this$props2 = this.props).makeStyles) === null || _this$props$makeStyle2 === void 0 ? void 0 : _this$props$makeStyle2.call(_this$props2);
+    var _this$props$makeStyle2, _this$props7;
+    (_this$props$makeStyle2 = (_this$props7 = this.props).makeStyles) === null || _this$props$makeStyle2 === void 0 ? void 0 : _this$props$makeStyle2.call(_this$props7);
+
+    // set focus on the currently active page
+    if (this.props.currentPage !== prevProps.currentPage && document.activeElement !== this._firstButton && document.activeElement !== this._prevButton && document.activeElement !== this._nextButton && document.activeElement !== this._lastButton) {
+      var _this$currentPageRef, _this$currentPageRef$, _this$currentPageRef$2;
+      // @ts-expect-error fix typing
+      (_this$currentPageRef = this.currentPageRef) === null || _this$currentPageRef === void 0 ? void 0 : (_this$currentPageRef$ = _this$currentPageRef.ref) === null || _this$currentPageRef$ === void 0 ? void 0 : (_this$currentPageRef$2 = _this$currentPageRef$.focus) === null || _this$currentPageRef$2 === void 0 ? void 0 : _this$currentPageRef$2.call(_this$currentPageRef$);
+    }
     if (!this.props.shouldHandleFocus || !propsHaveCompactView(prevProps) && !propsHaveCompactView(this.props)) {
       return;
     } else {
@@ -174,6 +291,7 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
     }, this.props.label);
   }
   renderPageInput(currentPageIndex) {
+    if (!this.props.children) return this.renderDefaultPageInput();
     return (0, _emotion.jsx)(_PaginationPageInput.PaginationPageInput, {
       numberOfPages: this.childPages.length,
       currentPageIndex: currentPageIndex,
@@ -189,6 +307,7 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
     (_this$childPages$page = (_this$childPages$page2 = this.childPages[pageIndex].props).onClick) === null || _this$childPages$page === void 0 ? void 0 : _this$childPages$page.call(_this$childPages$page2, event);
   }
   renderPages(currentPageIndex) {
+    if (!this.props.children) return this.renderDefaultPages();
     const allPages = this.childPages;
     let visiblePages = allPages;
     if (this.compactView) {
@@ -256,8 +375,8 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
   }
   renderArrowButton(direction, currentPageIndex) {
     var _page$props, _page$props2;
+    if (!this.props.children) return this.renderDefaultArrowButton(direction);
     const childPages = this.childPages;
-
     // We don't display the arrows in "compact" variant under 6 items
     if (!(propsHaveCompactView(this.props) || this.inputMode)) {
       return null;
@@ -265,11 +384,11 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
     if (!this.withFirstAndLastButton && (direction === 'first' || direction === 'last')) {
       return null;
     }
-    const _this$getArrowVariant = this.getArrowVariant(direction, currentPageIndex, childPages.length),
-      pageIndex = _this$getArrowVariant.pageIndex,
-      label = _this$getArrowVariant.label,
-      shouldEnableIcon = _this$getArrowVariant.shouldEnableIcon,
-      handleButtonRef = _this$getArrowVariant.handleButtonRef;
+    const _this$getArrowVariant2 = this.getArrowVariant(direction, currentPageIndex, childPages.length),
+      pageIndex = _this$getArrowVariant2.pageIndex,
+      label = _this$getArrowVariant2.label,
+      shouldEnableIcon = _this$getArrowVariant2.shouldEnableIcon,
+      handleButtonRef = _this$getArrowVariant2.handleButtonRef;
     const page = childPages[pageIndex];
     const disabled = (page === null || page === void 0 ? void 0 : (_page$props = page.props) === null || _page$props === void 0 ? void 0 : _page$props.disabled) || this.props.disabled || !shouldEnableIcon;
     const onClick = page === null || page === void 0 ? void 0 : (_page$props2 = page.props) === null || _page$props2 === void 0 ? void 0 : _page$props2.onClick;
@@ -284,7 +403,6 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
   }
   render() {
     var _this$props$styles, _this$props$styles2;
-    if (!this.props.children) return null;
     const currentPageIndex = fastFindIndex(this.childPages, p => p && p.props && p.props.current);
     const passthroughProps = _View.View.omitViewProps((0, _omitProps.omitProps)(this.props, Pagination.allowedProps), Pagination);
     return (0, _emotion.jsx)(_View.View, Object.assign({}, passthroughProps, {
@@ -307,6 +425,12 @@ let Pagination = exports.Pagination = (_dec = (0, _withDeterministicId.withDeter
   as: 'div',
   labelNumberInput: numberOfPages => `of ${numberOfPages}`,
   screenReaderLabelNumberInput: (currentPage, numberOfPages) => `Select page (${currentPage} of ${numberOfPages})`,
-  shouldHandleFocus: true
+  shouldHandleFocus: true,
+  totalPageNumber: 0,
+  currentPage: 1,
+  siblingCount: 1,
+  boundaryCount: 1,
+  ellipsis: '...',
+  renderPageIndicator: page => page
 }, _class2.Page = _PaginationButton.PaginationButton, _class2.Navigation = _PaginationArrowButton.PaginationArrowButton, _class2)) || _class) || _class) || _class);
 var _default = exports.default = Pagination;

package/lib/Pagination/props.js

@@ -50,6 +50,13 @@ const propTypes = exports.propTypes = {
   as: _propTypes.default.elementType,
   elementRef: _propTypes.default.func,
   inputRef: _propTypes.default.func,
-  shouldHandleFocus: _propTypes.default.bool
+  shouldHandleFocus: _propTypes.default.bool,
+  totalPageNumber: _propTypes.default.number,
+  currentPage: _propTypes.default.number,
+  siblingCount: _propTypes.default.number,
+  boundaryCount: _propTypes.default.number,
+  onPageChange: _propTypes.default.func,
+  renderPageIndicator: _propTypes.default.func,
+  ellipsis: _propTypes.default.node
 };
-const allowedProps = exports.allowedProps = ['children', 'disabled', 'withFirstAndLastButton', 'showDisabledButtons', 'label', 'labelNext', 'labelPrev', 'labelFirst', 'labelLast', 'labelNumberInput', 'screenReaderLabelNumberInput', 'variant', 'margin', 'as', 'elementRef', 'inputRef', 'shouldHandleFocus'];
+const allowedProps = exports.allowedProps = ['children', 'disabled', 'withFirstAndLastButton', 'showDisabledButtons', 'label', 'labelNext', 'labelPrev', 'labelFirst', 'labelLast', 'labelNumberInput', 'screenReaderLabelNumberInput', 'variant', 'margin', 'as', 'elementRef', 'inputRef', 'shouldHandleFocus', 'totalPageNumber', 'currentPage', 'onPageChange', 'siblingCount', 'boundaryCount', 'renderPageIndicator', 'ellipsis'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-pagination",
-  "version": "8.51.0",
+  "version": "8.51.1-snapshot-6",
   "description": "A UI component library made by Instructure Inc.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -23,29 +23,31 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@instructure/ui-babel-preset": "8.51.0",
-    "@instructure/ui-test-locator": "8.51.0",
-    "@instructure/ui-test-queries": "8.51.0",
-    "@instructure/ui-test-utils": "8.51.0"
+    "@instructure/ui-babel-preset": "8.51.1-snapshot-6",
+    "@instructure/ui-test-locator": "8.51.1-snapshot-6",
+    "@instructure/ui-test-queries": "8.51.1-snapshot-6",
+    "@instructure/ui-test-utils": "8.51.1-snapshot-6",
+    "@testing-library/jest-dom": "^6.1.4",
+    "@testing-library/react": "^14.0.0"
   },
   "dependencies": {
     "@babel/runtime": "^7.23.2",
-    "@instructure/emotion": "8.51.0",
-    "@instructure/shared-types": "8.51.0",
-    "@instructure/ui-a11y-content": "8.51.0",
-    "@instructure/ui-a11y-utils": "8.51.0",
-    "@instructure/ui-buttons": "8.51.0",
-    "@instructure/ui-dom-utils": "8.51.0",
-    "@instructure/ui-icons": "8.51.0",
-    "@instructure/ui-number-input": "8.51.0",
-    "@instructure/ui-portal": "8.51.0",
-    "@instructure/ui-prop-types": "8.51.0",
-    "@instructure/ui-react-utils": "8.51.0",
-    "@instructure/ui-testable": "8.51.0",
-    "@instructure/ui-tooltip": "8.51.0",
-    "@instructure/ui-utils": "8.51.0",
-    "@instructure/ui-view": "8.51.0",
-    "@instructure/uid": "8.51.0",
+    "@instructure/emotion": "8.51.1-snapshot-6",
+    "@instructure/shared-types": "8.51.1-snapshot-6",
+    "@instructure/ui-a11y-content": "8.51.1-snapshot-6",
+    "@instructure/ui-a11y-utils": "8.51.1-snapshot-6",
+    "@instructure/ui-buttons": "8.51.1-snapshot-6",
+    "@instructure/ui-dom-utils": "8.51.1-snapshot-6",
+    "@instructure/ui-icons": "8.51.1-snapshot-6",
+    "@instructure/ui-number-input": "8.51.1-snapshot-6",
+    "@instructure/ui-portal": "8.51.1-snapshot-6",
+    "@instructure/ui-prop-types": "8.51.1-snapshot-6",
+    "@instructure/ui-react-utils": "8.51.1-snapshot-6",
+    "@instructure/ui-testable": "8.51.1-snapshot-6",
+    "@instructure/ui-tooltip": "8.51.1-snapshot-6",
+    "@instructure/ui-utils": "8.51.1-snapshot-6",
+    "@instructure/ui-view": "8.51.1-snapshot-6",
+    "@instructure/uid": "8.51.1-snapshot-6",
     "keycode": "^2.2.1",
     "prop-types": "^15.8.1"
   },

package/src/Pagination/README.md

@@ -2,6 +2,285 @@
 describes: Pagination
 ---
 
+### NOTE
+
+Pagination is in a state of transition. Its API has been expanded to allow
+as close to zero config usage as possible, without introducing breaking changes to the previous methods.
+
+The component is under review by the design team and it's possible we'll deprecate te "old" API in a
+following version. If you're able to, please use the "new" API. Its documentation is on the top of this page.
+
+One of the biggest improvement is that pagination now can handle large page numbers as well.
+
+### Pagination
+
+The pagination component provides props to handle most of the pagination use-cases. These following examples are the same as the "old" examples in behaviour, but with the "new" API
+
+- ```js
+  class Example extends React.Component {
+    constructor(props) {
+      super(props)
+      this.state = { currentPage: 1 }
+    }
+
+    render() {
+      return (
+        <Pagination
+          as="nav"
+          margin="small"
+          variant="compact"
+          labelNext="Next Page"
+          labelPrev="Previous Page"
+          currentPage={this.state.currentPage}
+          totalPageNumber={9}
+          onPageChange={(nextPage) => this.setState({ currentPage: nextPage })}
+        />
+      )
+    }
+  }
+
+  render(<Example />)
+  ```
+
+- ```js
+  const Example = () => {
+    const [currentPage, setCurrentPage] = useState(1)
+
+    return (
+      <Pagination
+        as="nav"
+        margin="small"
+        variant="compact"
+        labelNext="Next Page"
+        labelPrev="Previous Page"
+        currentPage={currentPage}
+        totalPageNumber={9}
+        onPageChange={(nextPage) => setCurrentPage(nextPage)}
+      />
+    )
+  }
+
+  render(<Example />)
+  ```
+
+You can set any `totalPageNumber`, the component can handle it easily. Furthermore, you can set
+`siblingCount`, which indicates how many pages are visible on either side of the `currentPage` and the
+`boundaryCount`, which indicates how many pages are visible in the beginning and end.
+
+- ```js
+  class Example extends React.Component {
+    constructor(props) {
+      super(props)
+      this.state = { currentPage: 1 }
+    }
+
+    render() {
+      return (
+        <Pagination
+          as="nav"
+          margin="small"
+          variant="compact"
+          labelNext="Next Page"
+          labelPrev="Previous Page"
+          currentPage={this.state.currentPage}
+          totalPageNumber={100000}
+          onPageChange={(nextPage) => this.setState({ currentPage: nextPage })}
+          siblingCount={3}
+          boundaryCount={2}
+        />
+      )
+    }
+  }
+
+  render(<Example />)
+  ```
+
+- ```js
+  const Example = () => {
+    const [currentPage, setCurrentPage] = useState(1)
+    return (
+      <Pagination
+        as="nav"
+        margin="small"
+        variant="compact"
+        labelNext="Next Page"
+        labelPrev="Previous Page"
+        currentPage={currentPage}
+        totalPageNumber={100000}
+        onPageChange={(nextPage) => setCurrentPage(nextPage)}
+        siblingCount={3}
+        boundaryCount={2}
+      />
+    )
+  }
+
+  render(<Example />)
+  ```
+
+You can only display 1000 pages at once.
+
+- ```js
+  class Example extends React.Component {
+    constructor(props) {
+      super(props)
+      this.state = { currentPage: 1 }
+    }
+
+    render() {
+      return (
+        <Pagination
+          as="nav"
+          margin="small"
+          variant="full"
+          labelNext="Next Page"
+          labelPrev="Previous Page"
+          currentPage={this.state.currentPage}
+          totalPageNumber={100000}
+          onPageChange={(nextPage) => this.setState({ currentPage: nextPage })}
+          siblingCount={3}
+          boundaryCount={2}
+        />
+      )
+    }
+  }
+
+  render(<Example />)
+  ```
+
+- ```js
+  const Example = () => {
+    const [currentPage, setCurrentPage] = useState(1)
+    return (
+      <Pagination
+        as="nav"
+        margin="small"
+        variant="full"
+        labelNext="Next Page"
+        labelPrev="Previous Page"
+        currentPage={currentPage}
+        totalPageNumber={100000}
+        onPageChange={(nextPage) => setCurrentPage(nextPage)}
+        siblingCount={3}
+        boundaryCount={2}
+      />
+    )
+  }
+
+  render(<Example />)
+  ```
+
+You can override the default page rendering with `renderPageIndicator`.
+
+- ```js
+  class Example extends React.Component {
+    constructor(props) {
+      super(props)
+      this.state = { currentPage: 1 }
+    }
+
+    pageMap = ['A-G', 'H-J', 'K-M', 'N-Q', 'R-Z']
+
+    render() {
+      return (
+        <Pagination
+          as="nav"
+          margin="small"
+          variant="full"
+          labelNext="Next Page"
+          labelPrev="Previous Page"
+          currentPage={this.state.currentPage}
+          totalPageNumber={5}
+          onPageChange={(nextPage) => this.setState({ currentPage: nextPage })}
+          siblingCount={5}
+          boundaryCount={0}
+          renderPageIndicator={(page) => this.pageMap[page - 1]}
+        />
+      )
+    }
+  }
+
+  render(<Example />)
+  ```
+
+- ```js
+  const Example = () => {
+    const [currentPage, setCurrentPage] = useState(1)
+
+    const pageMap = ['A-G', 'H-J', 'K-M', 'N-Q', 'R-Z']
+
+    return (
+      <Pagination
+        as="nav"
+        margin="small"
+        variant="full"
+        labelNext="Next Page"
+        labelPrev="Previous Page"
+        currentPage={currentPage}
+        totalPageNumber={5}
+        onPageChange={(nextPage) => setCurrentPage(nextPage)}
+        siblingCount={5}
+        boundaryCount={0}
+        renderPageIndicator={(page) => pageMap[page - 1]}
+      />
+    )
+  }
+
+  render(<Example />)
+  ```
+
+The `variant="input"` prop will render Pagination with a NumberInput and all the arrow buttons.
+
+- ```js
+  class Example extends React.Component {
+    constructor(props) {
+      super(props)
+      this.state = { currentPage: 1 }
+    }
+
+    render() {
+      return (
+        <Pagination
+          as="nav"
+          margin="small"
+          variant="input"
+          labelNext="Next Page"
+          labelPrev="Previous Page"
+          currentPage={this.state.currentPage}
+          totalPageNumber={9}
+          onPageChange={(nextPage) => this.setState({ currentPage: nextPage })}
+        />
+      )
+    }
+  }
+
+  render(<Example />)
+  ```
+
+- ```js
+  const Example = () => {
+    const [currentPage, setCurrentPage] = useState(1)
+
+    return (
+      <Pagination
+        as="nav"
+        margin="small"
+        variant="input"
+        labelNext="Next Page"
+        labelPrev="Previous Page"
+        currentPage={currentPage}
+        totalPageNumber={9}
+        onPageChange={(nextPage) => setCurrentPage(nextPage)}
+      />
+    )
+  }
+
+  render(<Example />)
+  ```
+
+### Legacy examples
+
+These provide possibly finer, but much more complicated control over the pagination component. They are still supported, but we recommend using the new API.
+
 Renders available pages of content, and reacts to selection of another page.
 Expects array of `Pagination.Page` children. Focus and announcement of page change is
 the responsibility of your app.