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

package/src/Pagination/PaginationPageInput/index.tsx

@@ -0,0 +1,242 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/** @jsx jsx */
+
+import React, { Component } from 'react'
+
+import { testable } from '@instructure/ui-testable'
+import { withStyle, jsx } from '@instructure/emotion'
+import { NumberInput } from '@instructure/ui-number-input'
+import { ScreenReaderContent } from '@instructure/ui-a11y-content'
+
+import generateStyle from './styles'
+import generateComponentTheme from './theme'
+
+import { propTypes, allowedProps } from './props'
+import type {
+  PaginationPageInputProps,
+  PaginationPageInputState
+} from './props'
+
+/**
+---
+parent: Pagination
+id: Pagination.PageInput
+---
+@tsProps
+**/
+@withStyle(generateStyle, generateComponentTheme)
+@testable()
+class PaginationPageInput extends Component<
+  PaginationPageInputProps,
+  PaginationPageInputState
+> {
+  static readonly componentId = 'Pagination.PageInput'
+
+  static propTypes = propTypes
+  static allowedProps = allowedProps
+  static defaultProps = {
+    disabled: false
+  }
+
+  ref: HTMLSpanElement | null = null
+  _inputRef: HTMLInputElement | null = null
+
+  constructor(props: PaginationPageInputProps) {
+    super(props)
+
+    this.state = this.initialState
+  }
+
+  get currentPage() {
+    return this.props.currentPageIndex + 1
+  }
+
+  get initialState() {
+    return {
+      number: this.currentPage,
+      value: `${this.currentPage}`
+    }
+  }
+
+  get MIN() {
+    return 1
+  }
+
+  get MAX() {
+    return this.props.numberOfPages
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate(prevProps: PaginationPageInputProps) {
+    this.props.makeStyles?.()
+
+    // when the current page changes from outside (e.g.: from arrow buttons),
+    // we update the initial state
+    if (this.props.currentPageIndex !== prevProps.currentPageIndex) {
+      this.resetInitialState()
+    }
+  }
+
+  resetInitialState() {
+    this.setState(this.initialState)
+  }
+
+  handleRef = (el: HTMLSpanElement | null) => {
+    this.ref = el
+  }
+
+  handleInputRef = (el: HTMLInputElement | null) => {
+    this._inputRef = el
+
+    if (typeof this.props.inputRef === 'function') {
+      this.props.inputRef(el)
+    }
+  }
+
+  handleChange = (
+    _event: React.ChangeEvent<HTMLInputElement>,
+    value: string
+  ) => {
+    let newValue = value
+
+    // if the last character was not a number, don't accept it
+    if (value.length > 0 && isNaN(value.slice(-1) as any)) {
+      newValue = value.slice(0, -1)
+    }
+
+    this.setState({
+      number: newValue ? Number(newValue) : this.MIN,
+      value: newValue
+    })
+  }
+
+  handleKeyDown(event: React.KeyboardEvent<HTMLInputElement>) {
+    const { key } = event
+
+    if (key.toLowerCase() === 'enter') {
+      const { value, number } = this.state
+
+      // If it is invalid, we reset the input to the current page
+      if (value === '' || isNaN(value as any)) {
+        this.resetInitialState()
+        return
+      }
+
+      this.setNewPage(event, number)
+    }
+  }
+
+  handleDecrement = (
+    event:
+      | React.KeyboardEvent<HTMLInputElement>
+      | React.MouseEvent<HTMLButtonElement>
+  ) => {
+    this.setNewPage(event, Math.floor(this.currentPage - 1))
+  }
+
+  handleIncrement = (
+    event:
+      | React.KeyboardEvent<HTMLInputElement>
+      | React.MouseEvent<HTMLButtonElement>
+  ) => {
+    this.setNewPage(event, Math.floor(this.currentPage + 1))
+  }
+
+  handleBlur = (event: React.FocusEvent<HTMLInputElement>) => {
+    this.setNewPage(event, Math.round(this.state.number))
+  }
+
+  getNumberWithinRange(n: number) {
+    if (n < this.MIN) return this.MIN
+    if (n > this.MAX) return this.MAX
+    return n
+  }
+
+  setNewPage(
+    event:
+      | React.KeyboardEvent<HTMLInputElement>
+      | React.MouseEvent<HTMLButtonElement>
+      | React.FocusEvent<HTMLInputElement>,
+    n: number
+  ) {
+    const number = this.getNumberWithinRange(n)
+
+    this.setState({
+      number,
+      value: `${number}`
+    })
+
+    this.props.onChange(event, number - 1)
+  }
+
+  renderLabel() {
+    const { label, numberOfPages, styles } = this.props
+
+    return typeof label === 'function' && label(numberOfPages) ? (
+      <span css={styles?.inputLabel}>{label(numberOfPages)}</span>
+    ) : null
+  }
+
+  renderScreenReaderLabel() {
+    const { screenReaderLabel, numberOfPages } = this.props
+    return (
+      <ScreenReaderContent>
+        {screenReaderLabel(this.currentPage, numberOfPages)}
+      </ScreenReaderContent>
+    )
+  }
+
+  render() {
+    const { styles, disabled } = this.props
+
+    return (
+      <span css={styles?.paginationPageInput} ref={this.handleRef}>
+        <span css={styles?.numberInput}>
+          <NumberInput
+            renderLabel={this.renderScreenReaderLabel()}
+            onBlur={this.handleBlur}
+            onChange={this.handleChange}
+            onDecrement={this.handleDecrement}
+            onIncrement={this.handleIncrement}
+            onKeyDown={this.handleKeyDown.bind(this)}
+            interaction={disabled ? 'disabled' : 'enabled'}
+            showArrows={false}
+            value={this.state.value}
+            width="100%"
+            textAlign="center"
+            inputRef={this.handleInputRef}
+          />
+        </span>
+        {this.renderLabel()}
+      </span>
+    )
+  }
+}
+
+export default PaginationPageInput
+export { PaginationPageInput }

package/src/Pagination/PaginationPageInput/props.ts

@@ -0,0 +1,112 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import PropTypes from 'prop-types'
+
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  PaginationPageInputTheme,
+  PropValidators
+} from '@instructure/shared-types'
+import React from 'react'
+
+type PaginationPageInputOwnProps = {
+  /**
+   * The number of pages in total
+   */
+  numberOfPages: number
+  /**
+   * The index of the current page
+   */
+  currentPageIndex: number
+  /**
+   * Fires when a new page index is selected
+   */
+  onChange: (
+    event:
+      | React.KeyboardEvent<HTMLInputElement>
+      | React.MouseEvent<HTMLButtonElement>
+      | React.FocusEvent<HTMLInputElement>,
+    pageIndex: number
+  ) => void
+  /**
+   * ScreenReaderLabel for number input
+   */
+  screenReaderLabel: (currentPage: number, numberOfPages: number) => string
+  /**
+   * Label for number input
+   */
+  label?: (numberOfPages: number) => React.ReactNode
+  /**
+   * Disables interaction with the input
+   */
+  disabled?: boolean
+  /**
+   * provides a reference to the underlying html root element
+   */
+  inputRef?: (element: Element | null) => void
+}
+
+type PropKeys = keyof PaginationPageInputOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type PaginationPageInputProps = PaginationPageInputOwnProps &
+  WithStyleProps<PaginationPageInputTheme, PaginationPageInputStyle>
+
+type PaginationPageInputStyle = ComponentStyle<
+  'paginationPageInput' | 'numberInput' | 'inputLabel'
+>
+
+type PaginationPageInputState = {
+  number: number
+  value: string
+}
+
+const propTypes: PropValidators<PropKeys> = {
+  numberOfPages: PropTypes.number.isRequired,
+  currentPageIndex: PropTypes.number.isRequired,
+  onChange: PropTypes.func.isRequired,
+  screenReaderLabel: PropTypes.func.isRequired,
+  label: PropTypes.func,
+  disabled: PropTypes.bool,
+  inputRef: PropTypes.func
+}
+
+const allowedProps: AllowedPropKeys = [
+  'numberOfPages',
+  'currentPageIndex',
+  'onChange',
+  'screenReaderLabel',
+  'label',
+  'disabled',
+  'inputRef'
+]
+
+export type {
+  PaginationPageInputProps,
+  PaginationPageInputStyle,
+  PaginationPageInputState
+}
+export { propTypes, allowedProps }

package/src/Pagination/PaginationPageInput/styles.ts

@@ -0,0 +1,60 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { PaginationPageInputTheme } from '@instructure/shared-types'
+import type { PaginationPageInputStyle } from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} state the state of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: PaginationPageInputTheme
+): PaginationPageInputStyle => {
+  return {
+    paginationPageInput: {
+      label: 'paginationPageInput',
+      display: 'inline-flex',
+      alignItems: 'center',
+      margin: `0 ${componentTheme.inputSpacing}`
+    },
+    numberInput: {
+      label: 'paginationPageInput__input',
+      width: componentTheme.inputWidth
+    },
+    inputLabel: {
+      label: 'paginationPageInput__inputLabel',
+      marginInlineStart: componentTheme.inputSpacing,
+      whiteSpace: 'nowrap'
+    }
+  }
+}
+
+export default generateStyle

package/src/Pagination/PaginationPageInput/theme.ts

@@ -0,0 +1,46 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { Theme } from '@instructure/ui-themes'
+import type { PaginationPageInputTheme } from '@instructure/shared-types'
+
+/**
+ * Generates the theme object for the component from the theme and provided additional information
+ * @param  {Object} theme The actual theme object.
+ * @return {Object} The final theme object with the overrides and component variables
+ */
+const generateComponentTheme = (theme: Theme): PaginationPageInputTheme => {
+  const { spacing } = theme
+
+  const componentVariables: PaginationPageInputTheme = {
+    inputSpacing: spacing.xSmall,
+    inputWidth: '4.5rem'
+  }
+
+  return {
+    ...componentVariables
+  }
+}
+
+export default generateComponentTheme

package/src/Pagination/README.md

@@ -119,6 +119,122 @@ example: true
   <Pagination.Page href="/pages/3">R-Z</Pagination.Page>
 </Pagination>
 ```
+
+The `variant="input"` prop will render Pagination with a NumberInput and all the arrow buttons.
+
+```js
+---
+example: true
+render: false
+---
+class Example extends React.Component {
+  constructor (props) {
+    super(props)
+    this.state = { currentPage: 0 }
+  }
+
+  setPage (page) {
+    this.setState({ currentPage: page })
+  }
+
+  render () {
+    const pages = Array.from(Array(9)).map((v, i) => <Pagination.Page
+      key={i}
+      onClick={this.setPage.bind(this, i)}
+      current={i === this.state.currentPage}>
+        {i + 1}
+    </Pagination.Page>)
+
+    return (
+      <Pagination
+        as="nav"
+        margin="small"
+        variant="input"
+        labelFirst="First Page"
+        labelPrev="Previous Page"
+        labelNext="Next Page"
+        labelLast="Last Page"
+      >
+        {pages}
+      </Pagination>
+    )
+  }
+}
+
+render(<Example />)
+```
+
+The `withFirstAndLastButton` prop makes the "Jump to first" and "Jump to last" buttons appear. The `labelFirst` and `labelLast` props set the labels for these buttons.
+
+The `showDisabledButtons` prop displays the unavailable navigation buttons as disabled instead of hiding them.
+
+```js
+---
+example: true
+render: false
+---
+class Example extends React.Component {
+  constructor (props) {
+    super(props)
+    this.state = {
+      currentPage: 0,
+      withFirstAndLastButton: true,
+      showDisabledButtons: true
+    }
+  }
+
+  setPage (page) {
+    this.setState({ currentPage: page })
+  }
+
+  render () {
+    const pages = Array.from(Array(9)).map((v, i) => <Pagination.Page
+      key={i}
+      onClick={this.setPage.bind(this, i)}
+      current={i === this.state.currentPage}>
+        {i + 1}
+    </Pagination.Page>)
+
+    return (
+      <div>
+        <FormFieldGroup description="Pagination Settings">
+          <Checkbox
+            checked={this.state.withFirstAndLastButton}
+            label="With First and Last buttons"
+            onChange={() => {
+              this.setState({ withFirstAndLastButton: !this.state.withFirstAndLastButton })
+            }}
+          />
+          <Checkbox
+            checked={this.state.showDisabledButtons}
+            label="Show disabled buttons"
+            onChange={() => {
+              this.setState({ showDisabledButtons: !this.state.showDisabledButtons })
+            }}
+          />
+        </FormFieldGroup>
+
+        <Pagination
+          as="nav"
+          margin="large small small"
+          variant="compact"
+          labelNext="Next Page"
+          labelPrev="Previous Page"
+          labelFirst="First Page"
+          labelLast="Last Page"
+          withFirstAndLastButton={ this.state.withFirstAndLastButton }
+          showDisabledButtons={ this.state.showDisabledButtons }
+        >
+          {pages}
+        </Pagination>
+      </div>
+    )
+  }
+}
+
+render(<Example />)
+```
+
 ### Guidelines
 
 ```js