@instructure/ui-pagination 8.13.1-snapshot.9 → 8.14.0

package/src/Pagination/index.tsx

@@ -34,32 +34,42 @@ import { withStyle, jsx } from '@instructure/emotion'
 
 import { PaginationButton } from './PaginationButton'
 import { PaginationArrowButton } from './PaginationArrowButton'
+import { PaginationPageInput } from './PaginationPageInput'
 
 import generateStyle from './styles'
 
+import type { PaginationPageProps } from './PaginationButton/props'
+import type { PaginationArrowDirections } from './PaginationArrowButton/props'
+
 import { propTypes, allowedProps } from './props'
-import type { PaginationProps } from './props'
+import type { PaginationProps, PaginationSnapshot } from './props'
 
 /** This is an [].findIndex optimized to work on really big, but sparse, arrays */
 // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'arr' implicitly has an 'any' type.
 const fastFindIndex = (arr, fn) =>
   Number(Object.keys(arr).find((k) => fn(arr[Number(k)])))
 
-// @ts-expect-error ts-migrate(7006) FIXME: Parameter 'props' implicitly has an 'any' type.
-function propsHaveCompactView(props) {
-  return props.variant === 'compact' && props?.children?.length > 5
+const childrenArray = (props: PaginationProps) => {
+  const { children } = props
+
+  if (!children) {
+    return []
+  }
+
+  return Array.isArray(children)
+    ? (children as React.ReactElement<PaginationPageProps>[])
+    : ([children] as React.ReactElement<PaginationPageProps>[])
 }
 
-// @ts-expect-error ts-migrate(7006) FIXME: Parameter 'props' implicitly has an 'any' type.
-function shouldShowPrevButton(props, currentPageIndex) {
-  return propsHaveCompactView(props) && currentPageIndex > 0
+function propsHaveCompactView(props: PaginationProps) {
+  return props.variant === 'compact' && childrenArray(props).length > 5
 }
 
-// @ts-expect-error ts-migrate(7006) FIXME: Parameter 'props' implicitly has an 'any' type.
-function shouldShowNextButton(props, currentPageIndex) {
-  return (
-    propsHaveCompactView(props) && currentPageIndex < props.children.length - 1
-  )
+type ArrowConfig = {
+  pageIndex: number
+  label: string
+  shouldEnableIcon: boolean
+  handleButtonRef: (el: HTMLButtonElement) => void
 }
 
 /**
@@ -67,7 +77,6 @@ function shouldShowNextButton(props, currentPageIndex) {
 category: components
 ---
 **/
-
 @withStyle(generateStyle, null)
 @testable()
 class Pagination extends Component<PaginationProps> {
@@ -78,31 +87,41 @@ class Pagination extends Component<PaginationProps> {
   static defaultProps = {
     children: null,
     disabled: false,
+    withFirstAndLastButton: false,
+    showDisabledButtons: false,
     variant: 'full',
     as: 'div',
     // @ts-expect-error ts-migrate(6133) FIXME: 'el' is declared but its value is never read.
     elementRef: (el) => {},
+    labelNumberInput: (numberOfPages: number) => `of ${numberOfPages}`,
+    screenReaderLabelNumberInput: (
+      currentPage: number,
+      numberOfPages: number
+    ) => `Select page (${currentPage} of ${numberOfPages})`,
     shouldHandleFocus: true
   }
 
   static Page = PaginationButton
   static Navigation = PaginationArrowButton
 
+  _labelId: string
+
   ref: Element | null = null
+  _inputRef: Element | null = null
+
+  _firstButton: HTMLButtonElement | null = null
+  _prevButton: HTMLButtonElement | null = null
+  _nextButton: HTMLButtonElement | null = null
+  _lastButton: HTMLButtonElement | null = null
 
   // @ts-expect-error ts-migrate(7019) FIXME: Rest parameter 'args' implicitly has an 'any[]' ty... Remove this comment to see the full error message
   constructor(...args) {
     // @ts-expect-error ts-migrate(2556) FIXME: Expected 1-2 arguments, but got 0 or more.
     super(...args)
 
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_labelId' does not exist on type 'Pagina... Remove this comment to see the full error message
     this._labelId = uid('Pagination')
-
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_prevButton' does not exist on type 'Pag... Remove this comment to see the full error message
-    this._prevButton = null
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_nextButton' does not exist on type 'Pag... Remove this comment to see the full error message
-    this._nextButton = null
   }
+
   get _root() {
     console.warn(
       '_root property is deprecated and will be removed in v9, please use ref instead'
@@ -111,40 +130,80 @@ class Pagination extends Component<PaginationProps> {
     return this.ref
   }
 
-  getSnapshotBeforeUpdate() {
+  get inputMode() {
+    return this.props.variant === 'input'
+  }
+
+  get childPages() {
+    return childrenArray(this.props)
+  }
+
+  get withFirstAndLastButton() {
+    return this.inputMode || this.props.withFirstAndLastButton
+  }
+
+  get showDisabledButtons() {
+    return this.inputMode || this.props.showDisabledButtons
+  }
+
+  getSnapshotBeforeUpdate(): PaginationSnapshot {
     const activeElement = getActiveElement()
 
-    return {
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_prevButton' does not exist on type 'Pag... Remove this comment to see the full error message
-      prevButtonFocused: this._prevButton === activeElement,
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_nextButton' does not exist on type 'Pag... Remove this comment to see the full error message
-      nextButtonFocused: this._nextButton === activeElement
+    if (
+      activeElement === this._firstButton ||
+      activeElement === this._prevButton ||
+      activeElement === this._nextButton ||
+      activeElement === this._lastButton
+    ) {
+      return { lastFocusedButton: activeElement as HTMLButtonElement }
+    } else {
+      return { lastFocusedButton: undefined }
     }
   }
 
   componentDidMount() {
-    // @ts-expect-error ts-migrate(2722) FIXME: Cannot invoke an object which is possibly 'undefin... Remove this comment to see the full error message
-    this.props.makeStyles()
+    this.props.makeStyles?.()
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'prevProps' implicitly has an 'any' type... Remove this comment to see the full error message
-  componentDidUpdate(prevProps, prevState, snapshot) {
-    // @ts-expect-error ts-migrate(2722) FIXME: Cannot invoke an object which is possibly 'undefin... Remove this comment to see the full error message
-    this.props.makeStyles()
+  componentDidUpdate(
+    prevProps: PaginationProps,
+    _prevState: unknown,
+    snapshot: PaginationSnapshot
+  ) {
+    this.props.makeStyles?.()
+
     if (
       !this.props.shouldHandleFocus ||
       (!propsHaveCompactView(prevProps) && !propsHaveCompactView(this.props))
     ) {
       return
+    } else {
+      this.focusElementAfterUpdate(snapshot)
     }
+  }
 
-    const { prevButtonFocused, nextButtonFocused } = snapshot || {}
+  focusElementAfterUpdate(snapshot: PaginationSnapshot) {
+    const { lastFocusedButton } = snapshot
 
-    if (prevButtonFocused || nextButtonFocused) {
+    if (lastFocusedButton) {
       const focusable = findTabbable(this.ref)
-      const focusIndex = prevButtonFocused ? 0 : focusable.length - 1
-      // @ts-expect-error ts-migrate(2554) FIXME:
-      focusable[focusIndex].focus()
+      const direction = lastFocusedButton.dataset.direction
+
+      // By default we want to focus the previously focused button
+      let nextFocusElement: Element = lastFocusedButton
+
+      // In case the button is not focusable anymore
+      // (disabled or not in the DOM), we focus to the next available page
+      if (!focusable.includes(nextFocusElement)) {
+        if (direction === 'first' || direction === 'prev') {
+          nextFocusElement = focusable[0]
+        }
+        if (direction === 'next' || direction === 'last') {
+          nextFocusElement = focusable[focusable.length - 1]
+        }
+      }
+
+      ;(nextFocusElement as HTMLElement).focus()
     }
   }
 
@@ -152,17 +211,15 @@ class Pagination extends Component<PaginationProps> {
     return propsHaveCompactView(this.props)
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'children' implicitly has an 'any' type.
-  transferDisabledPropToChildren(children) {
-    return this.props.disabled
+  transferDisabledPropToChildren(children: PaginationProps['children']) {
+    return children && this.props.disabled
       ? React.Children.map(children, (page) =>
           React.cloneElement(page, { disabled: this.props.disabled })
         )
       : children
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'el' implicitly has an 'any' type.
-  handleElementRef = (el) => {
+  handleElementRef = (el: Element | null) => {
     this.ref = el
     if (el) {
       if (typeof this.props.elementRef === 'function') {
@@ -171,8 +228,12 @@ class Pagination extends Component<PaginationProps> {
     }
   }
 
+  handleInputRef = (el: Element | null) => {
+    this._inputRef = el
+  }
+
   renderLabel() {
-    const display = this.props.variant === 'compact' ? 'block' : 'inline-block'
+    const display = this.props.variant === 'full' ? 'inline-block' : 'block'
     const visibleLabel = hasVisibleChildren(this.props.label)
 
     return (
@@ -180,7 +241,6 @@ class Pagination extends Component<PaginationProps> {
         as="span"
         padding={visibleLabel ? 'small' : '0'}
         display={visibleLabel ? display : 'auto'}
-        // @ts-expect-error ts-migrate(2339) FIXME: Property '_labelId' does not exist on type 'Pagina... Remove this comment to see the full error message
         id={this._labelId}
       >
         {this.props.label}
@@ -188,14 +248,36 @@ class Pagination extends Component<PaginationProps> {
     )
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'currentPageIndex' implicitly has an 'an... Remove this comment to see the full error message
-  renderPages(currentPageIndex) {
-    const allPages = this.props.children
+  renderPageInput(currentPageIndex: number) {
+    return (
+      <PaginationPageInput
+        numberOfPages={this.childPages.length}
+        currentPageIndex={currentPageIndex}
+        onChange={this.handleInputChange.bind(this)}
+        screenReaderLabel={this.props.screenReaderLabelNumberInput!}
+        label={this.props.labelNumberInput}
+        disabled={this.props.disabled}
+        inputRef={this.handleInputRef}
+      />
+    )
+  }
+
+  handleInputChange(
+    event:
+      | React.KeyboardEvent<HTMLInputElement>
+      | React.MouseEvent<HTMLButtonElement>
+      | React.FocusEvent<HTMLInputElement>,
+    pageIndex: number
+  ) {
+    this.childPages[pageIndex].props.onClick?.(event)
+  }
+
+  renderPages(currentPageIndex: number) {
+    const allPages = this.childPages
     let visiblePages = allPages
 
     if (this.compactView) {
       const firstIndex = 0
-      // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
       const lastIndex = allPages.length - 1
 
       const sliceStart = Math.min(
@@ -204,31 +286,24 @@ class Pagination extends Component<PaginationProps> {
       )
       const sliceEnd = Math.min(currentPageIndex + 4, lastIndex)
 
-      // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
       visiblePages = allPages.slice(sliceStart, sliceEnd)
 
-      // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
       const firstPage = allPages[firstIndex]
-      // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
       const lastPage = allPages[lastIndex]
 
       if (sliceStart - firstIndex > 1)
-        // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
         visiblePages.unshift(
           <span key="first" aria-hidden="true">
             &hellip;
           </span>
         )
-      // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
       if (sliceStart - firstIndex > 0) visiblePages.unshift(firstPage)
       if (lastIndex - sliceEnd + 1 > 1)
-        // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
         visiblePages.push(
           <span key="last" aria-hidden="true">
             &hellip;
           </span>
         )
-      // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
       if (lastIndex - sliceEnd + 1 > 0) visiblePages.push(lastPage)
     }
 
@@ -239,33 +314,88 @@ class Pagination extends Component<PaginationProps> {
     )
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'label' implicitly has an 'any' type.
-  renderArrowButton(label, direction, currentPageIndex) {
-    // eslint-disable-next-line react/prop-types
-    const { onClick, disabled } =
-      // @ts-expect-error ts-migrate(2533) FIXME: Object is possibly 'null' or 'undefined'.
-      this.props.children[currentPageIndex + direction].props
-
-    // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'el' implicitly has an 'any' type.
-    const handleButtonRef = (el) => {
-      if (direction < 0) {
-        // @ts-expect-error ts-migrate(2339) FIXME: Property '_prevButton' does not exist on type 'Pag... Remove this comment to see the full error message
-        this._prevButton = el
-      } else {
-        // @ts-expect-error ts-migrate(2339) FIXME: Property '_nextButton' does not exist on type 'Pag... Remove this comment to see the full error message
-        this._nextButton = el
-      }
+  getArrowVariant(
+    direction: PaginationArrowDirections,
+    currentPageIndex: number,
+    pagesCount: number
+  ): ArrowConfig {
+    switch (direction) {
+      case 'first':
+        return {
+          pageIndex: 0,
+          label: this.props.labelFirst || 'First Page',
+          shouldEnableIcon: currentPageIndex > 1,
+          handleButtonRef: (el) => {
+            this._firstButton = el
+          }
+        }
+      case 'prev':
+        return {
+          pageIndex: currentPageIndex - 1,
+          label: this.props.labelPrev || 'Previous Page',
+          shouldEnableIcon: currentPageIndex > 0,
+          handleButtonRef: (el) => {
+            this._prevButton = el
+          }
+        }
+      case 'next':
+        return {
+          pageIndex: currentPageIndex + 1,
+          label: this.props.labelNext || 'Next Page',
+          shouldEnableIcon: currentPageIndex < pagesCount - 1,
+          handleButtonRef: (el) => {
+            this._nextButton = el
+          }
+        }
+      case 'last':
+        return {
+          pageIndex: pagesCount - 1,
+          label: this.props.labelLast || 'Last Page',
+          shouldEnableIcon: currentPageIndex < pagesCount - 2,
+          handleButtonRef: (el) => {
+            this._lastButton = el
+          }
+        }
     }
+  }
 
-    return (
+  renderArrowButton(
+    direction: PaginationArrowDirections,
+    currentPageIndex: number
+  ) {
+    const { childPages } = this
+
+    // We don't display the arrows in "compact" variant under 6 items
+    if (!(propsHaveCompactView(this.props) || this.inputMode)) {
+      return null
+    }
+
+    if (
+      !this.withFirstAndLastButton &&
+      (direction === 'first' || direction === 'last')
+    ) {
+      return null
+    }
+
+    const { pageIndex, label, shouldEnableIcon, handleButtonRef } =
+      this.getArrowVariant(direction, currentPageIndex, childPages.length)
+
+    const page = childPages[pageIndex]
+
+    const disabled =
+      page?.props?.disabled || this.props.disabled || !shouldEnableIcon
+    const onClick = page?.props?.onClick
+
+    return shouldEnableIcon || this.showDisabledButtons ? (
       <PaginationArrowButton
-        direction={direction === -1 ? 'prev' : 'next'}
+        direction={direction}
+        data-direction={direction}
         label={label}
         onClick={onClick}
         disabled={disabled}
         buttonRef={handleButtonRef}
       />
-    )
+    ) : null
   }
 
   render() {
@@ -290,16 +420,19 @@ class Pagination extends Component<PaginationProps> {
         elementRef={this.handleElementRef}
         margin={this.props.margin}
         css={this.props.styles?.pagination}
-        // @ts-expect-error ts-migrate(2339) FIXME: Property '_labelId' does not exist on type 'Pagina... Remove this comment to see the full error message
-        aria-labelledby={this.props.label && this._labelId}
+        aria-labelledby={this.props.label ? this._labelId : undefined}
       >
         {this.props.label && this.renderLabel()}
         <View display="inline-block" css={this.props.styles?.pages}>
-          {shouldShowPrevButton(this.props, currentPageIndex) &&
-            this.renderArrowButton(this.props.labelPrev, -1, currentPageIndex)}
-          {this.renderPages(currentPageIndex)}
-          {shouldShowNextButton(this.props, currentPageIndex) &&
-            this.renderArrowButton(this.props.labelNext, 1, currentPageIndex)}
+          {this.renderArrowButton('first', currentPageIndex)}
+          {this.renderArrowButton('prev', currentPageIndex)}
+
+          {this.inputMode
+            ? this.renderPageInput(currentPageIndex)
+            : this.renderPages(currentPageIndex)}
+
+          {this.renderArrowButton('next', currentPageIndex)}
+          {this.renderArrowButton('last', currentPageIndex)}
         </View>
       </View>
     )

package/src/Pagination/props.ts

@@ -40,14 +40,29 @@ import type {
   OtherHTMLAttributes,
   PropValidators
 } from '@instructure/shared-types'
+import type { PaginationPageProps } from './PaginationButton/props'
 
 type PaginationOwnProps = {
-  children?: React.ReactNode // TODO: oneof([PaginationButton])
+  // this won't filter the children completely well,
+  // it will allow simple elements (e.g. `<div>`) and components with compatible props
+  // TODO: find a better way to type Children.oneOf([PaginationButton])
+  children?:
+    | React.ReactElement<PaginationPageProps>
+    | React.ReactElement<PaginationPageProps>[]
   disabled?: boolean
+  withFirstAndLastButton?: boolean
+  showDisabledButtons?: boolean
   label?: React.ReactNode
   labelNext?: string
   labelPrev?: string
-  variant?: 'full' | 'compact'
+  labelFirst?: string
+  labelLast?: string
+  labelNumberInput?: (numberOfPages: number) => React.ReactNode
+  screenReaderLabelNumberInput?: (
+    currentPage: number,
+    numberOfPages: number
+  ) => string
+  variant?: 'full' | 'compact' | 'input'
   margin?: Spacing
   as?: AsElementType
   elementRef?: (element: Element | null) => void
@@ -73,6 +88,14 @@ const propTypes: PropValidators<PropKeys> = {
    * Disables interaction with all pages
    */
   disabled: PropTypes.bool,
+  /**
+   * Displays "jump to first" and "jump to last" buttons. Always turned on with `input` variant.
+   */
+  withFirstAndLastButton: PropTypes.bool,
+  /**
+   * Displays the unavailable navigation buttons as disabled instead of hiding them.  Always turned on with `input` variant.
+   */
+  showDisabledButtons: PropTypes.bool,
   /**
    * Visible label for component
    */
@@ -85,12 +108,28 @@ const propTypes: PropValidators<PropKeys> = {
    * Accessible label for previous button
    */
   labelPrev: PropTypes.string,
+  /**
+   * Accessible label for "jump to first" button
+   */
+  labelFirst: PropTypes.string,
+  /**
+   * Accessible label for "jump to last" button
+   */
+  labelLast: PropTypes.string,
+  /**
+   * Label for number input (for `input` variant)
+   */
+  labelNumberInput: PropTypes.func,
+  /**
+   * ScreenReaderLabel for number input (for `input` variant)
+   */
+  screenReaderLabelNumberInput: PropTypes.func,
   /**
    * The compact variant truncates the page navigation to show only the first,
    * last, and pages immediately surrounding the current page. Fewer than 5 pages,
    * no next/previous arrow buttons will be shown, and all pages will be listed
    */
-  variant: PropTypes.oneOf(['full', 'compact']),
+  variant: PropTypes.oneOf(['full', 'compact', 'input']),
   /**
    * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,
    * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via
@@ -116,9 +155,15 @@ const propTypes: PropValidators<PropKeys> = {
 const allowedProps: AllowedPropKeys = [
   'children',
   'disabled',
+  'withFirstAndLastButton',
+  'showDisabledButtons',
   'label',
   'labelNext',
   'labelPrev',
+  'labelFirst',
+  'labelLast',
+  'labelNumberInput',
+  'screenReaderLabelNumberInput',
   'variant',
   'margin',
   'as',
@@ -126,5 +171,9 @@ const allowedProps: AllowedPropKeys = [
   'shouldHandleFocus'
 ]
 
-export type { PaginationProps, PaginationStyle }
+type PaginationSnapshot = {
+  lastFocusedButton?: HTMLButtonElement
+}
+
+export type { PaginationProps, PaginationStyle, PaginationSnapshot }
 export { propTypes, allowedProps }

package/tsconfig.build.json

@@ -1,7 +1,31 @@
 {
   "extends": "../../tsconfig.build.json",
   "compilerOptions": {
-    "outDir": "./types"
+    "outDir": "./types",
+    "rootDir": "./src",
+    "composite": true
   },
-  "include": ["src/**/*"]
+  "include": ["src"],
+  "references": [
+    { "path": "../ui-babel-preset/tsconfig.build.json" },
+    { "path": "../ui-test-locator/tsconfig.build.json" },
+    { "path": "../ui-test-queries/tsconfig.build.json" },
+    { "path": "../ui-test-utils/tsconfig.build.json" },
+    { "path": "../emotion/tsconfig.build.json" },
+    { "path": "../shared-types/tsconfig.build.json" },
+    { "path": "../ui-a11y-content/tsconfig.build.json" },
+    { "path": "../ui-a11y-utils/tsconfig.build.json" },
+    { "path": "../ui-buttons/tsconfig.build.json" },
+    { "path": "../ui-dom-utils/tsconfig.build.json" },
+    { "path": "../ui-icons/tsconfig.build.json" },
+    { "path": "../ui-portal/tsconfig.build.json" },
+    { "path": "../ui-prop-types/tsconfig.build.json" },
+    { "path": "../ui-react-utils/tsconfig.build.json" },
+    { "path": "../ui-testable/tsconfig.build.json" },
+    { "path": "../ui-tooltip/tsconfig.build.json" },
+    { "path": "../ui-utils/tsconfig.build.json" },
+    { "path": "../ui-view/tsconfig.build.json" },
+    { "path": "../uid/tsconfig.build.json" },
+    { "path": "../ui-number-input/tsconfig.build.json" }
+  ]
 }