Pagination prop audit

enigma-io · Feb 3, 2017 · f95da0b · f95da0b
1 parent 8cdef4b
commit f95da0b
Show file tree

Hide file tree

Showing 4 changed files with 444 additions and 358 deletions.
diff --git a/packages/boundless-pagination/README.md b/packages/boundless-pagination/README.md
@@ -9,13 +9,13 @@ Pagination is implemented as an encapsulated view system, accepting an array of
 
 ## Component Instance Methods
 
-When using `Pagination` in your project, you may call the following methods on a rendered instance of the component. Use [`refs`](https://facebook.github.io/react/docs/refs-and-the-dom.html) to get the instance.
+When using `Pagination` in your project, you may call the following methods on a rendered
+instance of the component. Use [`refs`](https:// * facebook.github.io/react/docs/refs-and-the-dom.html)
+to get the instance.
 
-- __`currentPage()`__
-  returns the ___one___-indexed page number currently in view
+- __`currentPage()`__ returns the ___one___-indexed page number currently in view
 
-- __`pageToIndex(index: number)`__
-  renders the page that contains the ___zero___-indexed item
+- __`jumpToIndex(index: number)`__ renders the page that contains the ___zero___-indexed item
 
 ## Example Usage
 ```jsx
@@ -68,11 +68,11 @@ export default class PaginationDemo extends React.PureComponent {
                 customControlContent='Your custom content'
                 getItem={this.handleItemRequest}
                 identifier={this.state.identifier}
-                itemToJSXConverterFunc={this.itemToJSX}
-                jumpToFirstControlContent='⇤'
-                previousPageControlContent='←'
-                nextPageControlContent='→'
-                jumpToLastControlContent='⇥'
+                itemToJSXConverter={this.itemToJSX}
+                jumpToFirstPageControlContent='⇤'
+                jumpToLastPageControlContent='⇥'
+                jumpToNextPageControlContent='→'
+                jumpToPreviousPageControlContent='←'
                 numItemsPerPage={5}
                 showPaginationState={true}
                 totalItems={this.state.items.length} />
@@ -89,7 +89,15 @@ export default class PaginationDemo extends React.PureComponent {
 
 ### Required Props
 
-- __`identifier`__ ・ a unique name for the dataset being consumed; pass a different name to cause the view to fully reset and pull brand new data
+- __`getItem`__ ・ called with a desired item index when that item comes into view;
+  accepts a `Promise` if you need to fetch the row asynchronously
+
+  Expects | Default Value
+  -       | -
+  `function` | `() => {}`
+
+- __`identifier`__ ・ a unique name for the data source being consumed; pass a
+  different name to cause the view to fully reset and pull fresh data
 
   Expects | Default Value
   -       | -
@@ -104,6 +112,12 @@ export default class PaginationDemo extends React.PureComponent {
 
 ### Optional Props
 
+- __`*`__ ・ any [React-supported attribute](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes)
+
+  Expects | Default Value
+  -       | -
+  `any` | `n/a`
+
 - __`after`__ ・ arbitrary content to be rendered after the items in the DOM
 
   Expects | Default Value
@@ -116,103 +130,139 @@ export default class PaginationDemo extends React.PureComponent {
   -       | -
   `any renderable` | `null`
 
-- __`customControlContent`__ ・ allows for arbitrary content to be rendered into the control area
+- __`controlWrapperProps`__
 
   Expects | Default Value
   -       | -
-  `any renderable` | `null`
+  `object` | `{}`
 
-- __`getItem`__ ・ called with a desired item index when that item comes into view; accepts a `Promise` if you need to fetch the row asynchronously
+- __`customControlContent`__ ・ allows for arbitrary content to be rendered into the control area
 
   Expects | Default Value
   -       | -
-  `function` | `() => {}`
+  `any renderable` | `null`
 
-- __`hidePagerIfNotNeeded`__ ・ does not render the paging controls if the number of items supplied to the view is less-than-or-equal-to the number of items to show per page via `props.numItemsPerPage`
+- __`hidePagerIfNotNeeded`__ ・ does not render the paging controls if the number of items supplied
+  to the view is less-than-or-equal-to the number of items to show
+  per page via `props.numItemsPerPage`
 
   Expects | Default Value
   -       | -
   `bool` | `false`
 
-- __`initialPage`__ ・ the (_one-indexed_) number of the page that should be initially displayed; must be a positive integer less than or equal to the total number of pages
+- __`initialPage`__ ・ the (__one-indexed__) number of the page that should be initially
+  displayed; must be a positive integer less than or equal to
+  the total number of pages
 
   Expects | Default Value
   -       | -
   `custom` | `1`
 
-- __`itemLoadingContent`__ ・ allows for arbitrary content to be rendered into pagination items as they're loading if the backing data is a `Promise`
+- __`itemLoadingContent`__ ・ allows for arbitrary content to be rendered into pagination items
+  as they're loading if the backing data is a `Promise`
 
   Expects | Default Value
   -       | -
   `any renderable` | `undefined`
 
-- __`itemToJSXConverterFunc`__ ・ an optional function to specify how an item should be converted to JSX, if it is not already renderable by React
+- __`itemToJSXConverter`__ ・ an function to specify how an item should be converted
+  to JSX, if it is not already renderable by React
+
+  ```jsx
+
+  const getItem = () => ({id: 1234, text: 'foo'});
+  const objToJSX = ({id, text}) => <div data-id={id}>{text}</div>;
+
+  <Pagination
+      getItem={getItem}
+      identifer='foo'
+      itemToJSXConverter={objToJSX}
+      totalItems={1} />
+  ```
 
   Expects | Default Value
   -       | -
   `function` | `(x) => x`
 
-- __`jumpToFirstControlContent`__ ・ content to be displayed inside of the "First page" control button
+- __`itemWrapperProps`__
 
   Expects | Default Value
   -       | -
-  `any renderable` | `'« First'`
+  `object` | `{}`
 
-- __`jumpToLastControlContent`__ ・ content to be displayed inside of the "Last page" control button
+- __`jumpToFirstPageControlContent`__ ・ content to be displayed inside of the "First page" control button
 
   Expects | Default Value
   -       | -
-  `any renderable` | `'Last »'`
+  `any renderable` | `'⇤'`
 
-- __`listWrapperProps`__ ・ any [React-supported attribute](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes); applied to the `.b-pagination-item-list` node
+- __`jumpToLastPageControlContent`__ ・ content to be displayed inside of the "Last page" control button
 
   Expects | Default Value
   -       | -
-  `object` | `{}`
+  `any renderable` | `'⇥'`
 
-- __`nextPageControlContent`__ ・ content to be displayed inside of the "Next page" control button
+- __`jumpToNextPageControlContent`__ ・ content to be displayed inside of the "Next page" control button
 
   Expects | Default Value
   -       | -
-  `any renderable` | `'Next ›'`
+  `any renderable` | `'→'`
 
-- __`numItemsPerPage`__ ・ the maximum number of items to be displayed on each page; must be greater than zero
+- __`jumpToPreviousPageControlContent`__ ・ content to be displayed inside of the "Previous page" control button
+
+  Expects | Default Value
+  -       | -
+  `any renderable` | `'←'`
+
+- __`numItemsPerPage`__ ・ the maximum number of items to be displayed on each page; must be
+  greater than zero
 
   Expects | Default Value
   -       | -
   `custom` | `10`
 
-- __`numPageToggles`__ ・ the maximum number of pages to be displayed in the control bar at one time
+- __`numPageToggles`__ ・ the maximum number of pages to be displayed in the control bar at
+  one time
 
   Expects | Default Value
   -       | -
   `number` | `5`
 
-- __`position`__ ・ determines whether the pagination controls are displayed above, below, or both above and below the content
+- __`position`__ ・ determines whether the pagination controls are displayed above,
+  below, or both above and below the content
+
+  Expects | Default Value
+  -       | -
+  `Pagination.position.ABOVE or Pagination.position.BELOW or Pagination.position.BOTH` | `Pagination.position.ABOVE`
+
+- __`showJumpToFirstPageControl`__ ・ whether the "first page" control button should be displayed
 
   Expects | Default Value
   -       | -
-  `` | `Pagination.positions.ABOVE`
+  `bool` | `true`
 
-- __`previousPageControlContent`__ ・ content to be displayed inside of the "Previous page" control button
+- __`showJumpToLastPageControl`__ ・ whether the "last page" control button should be displayed
 
   Expects | Default Value
   -       | -
-  `any renderable` | `'‹ Previous'`
+  `bool` | `true`
 
-- __`showJumpToFirst`__ ・ whether the "First page" control button should be displayed
+- __`showJumpToNextPageControl`__ ・ whether the "next page" control button should be displayed
 
   Expects | Default Value
   -       | -
   `bool` | `true`
 
-- __`showJumpToLast`__ ・ whether the "Last page" control button should be displayed
+- __`showJumpToPreviousPageControl`__ ・ whether the "previous page" control button should be displayed
 
   Expects | Default Value
   -       | -
   `bool` | `true`
 
-- __`showPaginationState`__ ・ renders an element called `.b-pagination-control-state` that contains the current state of the pagination like "1 of 10"; alternatively, this prop also accepts a function that it will call with the currentPage and totalPages for you to format:
+- __`showPaginationState`__ ・ renders an element called `.b-pagination-control-state` that
+  contains the current state of the pagination like "1 of 10";
+  alternatively, this prop also accepts a function that it will
+  call with the currentPage and totalPages for you to format:
 
   ```jsx
   showPaginatedState={
@@ -228,12 +278,6 @@ export default class PaginationDemo extends React.PureComponent {
   -       | -
   `bool or function` | `true`
 
-- __`toggleWrapperProps`__ ・ any [React-supported attribute](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes); applied to the SegmentedControl node(s), `.b-pagination-controls`
-
-  Expects | Default Value
-  -       | -
-  `object` | `{}`
-
 
 ## Reference Styles
 ### Stylus

diff --git a/packages/boundless-pagination/demo/index.js b/packages/boundless-pagination/demo/index.js
@@ -47,11 +47,11 @@ export default class PaginationDemo extends React.PureComponent {
                 customControlContent='Your custom content'
                 getItem={this.handleItemRequest}
                 identifier={this.state.identifier}
-                itemToJSXConverterFunc={this.itemToJSX}
-                jumpToFirstControlContent='⇤'
-                previousPageControlContent='←'
-                nextPageControlContent='→'
-                jumpToLastControlContent='⇥'
+                itemToJSXConverter={this.itemToJSX}
+                jumpToFirstPageControlContent='⇤'
+                jumpToLastPageControlContent='⇥'
+                jumpToNextPageControlContent='→'
+                jumpToPreviousPageControlContent='←'
                 numItemsPerPage={5}
                 showPaginationState={true}
                 totalItems={this.state.items.length} />