@canonical/react-components 0.49.0 → 0.50.0

package/dist/components/TablePagination/TablePagination.d.ts

@@ -1,6 +1,6 @@
 import React, { HTMLAttributes, PropsWithChildren, ReactNode } from "react";
 import "./TablePagination.scss";
-export type Props = PropsWithChildren<{
+export type BasePaginationProps = {
     /**
      * list of data elements to be paginated. This component is un-opinionated about
      * the structure of the data but it should be identical to the data structure
@@ -9,7 +9,7 @@ export type Props = PropsWithChildren<{
     data: unknown[];
     /**
      * prop name of the child table component that receives paginated data.
-     * default value is set to @constant rows, which is the data prop for the @func MainTable component
+     * default value is set to `rows`, which is the data prop for the `MainTable` component
      */
     dataForwardProp?: string;
     /**
@@ -32,6 +32,46 @@ export type Props = PropsWithChildren<{
      * place the pagination component above or below the table?
      */
     position?: "above" | "below";
-}> & HTMLAttributes<HTMLDivElement>;
-declare const TablePagination: ({ data, className, itemName, description, position, dataForwardProp, pageLimits, children, ...divProps }: Props) => React.JSX.Element;
+};
+export type ExternalControlProps = BasePaginationProps & {
+    /**
+     * Whether the component will be controlled via external state.
+     */
+    externallyControlled?: true;
+    /**
+     * the total number of items available within the data. This prop is only relevant
+     * and will be required if `externallyControlled` is set to `true`.
+     */
+    totalItems: number;
+    /**
+     * the current page that's showing. This prop is only relevant and will be required
+     * if `externallyControlled` is set to `true`.
+     */
+    currentPage: number;
+    /**
+     * size per page. This prop is only relevant and will be required if
+     * `externallyControlled` is set to `true`.
+     */
+    pageSize: number;
+    /**
+     * callback indicating a page change event to the parent component.
+     * This prop is only relevant and will be required if `externallyControlled` is set
+     * to `true`.
+     */
+    onPageChange: (page: number) => void;
+    /**
+     * callback indicating a page size change event to the parent component.
+     * This prop is only relevant and will be required if `externallyControlled` is set
+     * to `true`.
+     */
+    onPageSizeChange: (pageSize: number) => void;
+};
+export type InternalControlProps = BasePaginationProps & {
+    /**
+     * Whether the component will be controlled via external state.
+     */
+    externallyControlled?: false;
+};
+export type Props = PropsWithChildren<ExternalControlProps | InternalControlProps> & HTMLAttributes<HTMLDivElement>;
+declare const TablePagination: (props: Props) => React.JSX.Element;
 export default TablePagination;

package/dist/components/TablePagination/TablePagination.js

@@ -5,121 +5,85 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
-var _classnames = _interopRequireDefault(require("classnames"));
-var _hooks = require("../../hooks");
-var _Select = _interopRequireDefault(require("../Select"));
-var _TablePaginationControls = _interopRequireDefault(require("./TablePaginationControls"));
 require("./TablePagination.scss");
+var _TablePaginationControls = _interopRequireDefault(require("./TablePaginationControls"));
+var _utils = require("./utils");
+var _hooks = require("../../hooks");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
 function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
-/**
- * Determine if we are working with a small screen.
- * 'small screen' in this case is relative to the width of the description div
- */
-const figureSmallScreen = descriptionRef => {
-  const descriptionElement = descriptionRef.current;
-  if (!descriptionElement) {
-    return true;
-  }
-  return descriptionElement.getBoundingClientRect().width < 230;
-};
-
-/**
- * Iterate direct react child components and override the value of the prop specified by @param dataForwardProp
- * for those child components.
- * @param children - react node children to iterate
- * @param dataForwardProp - the name of the prop from the children components to override
- * @param data - actual data to be passed to the prop specified by @param dataForwardProp
- */
-const renderChildren = (children, dataForwardProp, data) => {
-  return _react.Children.map(children, child => {
-    return /*#__PURE__*/(0, _react.cloneElement)(child, {
-      [dataForwardProp]: data
-    });
-  });
-};
-const DEFAULT_PAGE_LIMITS = [50, 100, 200];
-const generatePagingOptions = pageLimits => {
-  return pageLimits.map(limit => ({
-    value: limit,
-    label: "".concat(limit, "/page")
-  }));
-};
-const TablePagination = _ref => {
-  let {
+const TablePagination = props => {
+  const {
     data,
-    className,
+    dataForwardProp = "rows",
     itemName = "item",
+    className,
     description,
+    pageLimits = _utils.DEFAULT_PAGE_LIMITS,
     position = "above",
-    dataForwardProp = "rows",
-    pageLimits = DEFAULT_PAGE_LIMITS,
+    externallyControlled,
     children,
     ...divProps
-  } = _ref;
-  const descriptionRef = (0, _react.useRef)(null);
-  const [isSmallScreen, setSmallScreen] = (0, _react.useState)(false);
-  const [pageSize, setPageSize] = (0, _react.useState)(() => {
-    return generatePagingOptions(pageLimits)[0].value;
+  } = props;
+
+  // Safety check to ensure pageSize is a valid option in
+  // pageLimits if the component is externally controlled
+  if (externallyControlled) {
+    let pageSizeFound = false;
+    for (const limit of pageLimits) {
+      if (limit === Number(props.pageSize)) {
+        pageSizeFound = true;
+        break;
+      }
+    }
+    if (!pageSizeFound) {
+      throw new Error("pageSize must be a valid option in pageLimits, pageLimits is set to [".concat(pageLimits, "]"));
+    }
+  }
+  const [internalPageSize, setInternalPageSize] = (0, _react.useState)(() => {
+    return (0, _utils.generatePagingOptions)(pageLimits)[0].value;
   });
   const {
     paginate,
-    currentPage,
-    pageData,
-    totalItems
-  } = (0, _hooks.usePagination)(data, {
-    itemsPerPage: pageSize,
+    currentPage: internalCurrentPage,
+    pageData: internalData
+  } = (0, _hooks.usePagination)(externallyControlled ? [] : data, {
+    itemsPerPage: internalPageSize,
     autoResetPage: true
   });
-  (0, _react.useEffect)(() => {
-    const handleResize = () => {
-      setSmallScreen(figureSmallScreen(descriptionRef));
-    };
-    window.addEventListener("resize", handleResize);
-    return () => {
-      window.removeEventListener("resize", handleResize);
-    };
-  }, [isSmallScreen]);
-  const handlePageSizeChange = e => {
-    paginate(1);
-    setPageSize(parseInt(e.target.value));
-  };
-  const getDescription = () => {
-    if (description) {
-      return description;
-    }
-    const visibleCount = pageData.length;
-    if (isSmallScreen) {
-      return "".concat(visibleCount, " out of ").concat(totalItems);
+  const controlData = externallyControlled ? data : internalData;
+  const controlPageSize = externallyControlled ? props.pageSize : internalPageSize;
+  const controlTotalItems = externallyControlled ? props.totalItems : data.length;
+  const controlCurrentPage = externallyControlled ? props.currentPage : internalCurrentPage;
+  const handlePageChange = page => {
+    if (externallyControlled) {
+      props.onPageChange(page);
+      return;
     }
-    if (visibleCount === totalItems && visibleCount > 1) {
-      return "Showing all ".concat(totalItems, " ").concat(itemName, "s");
+    paginate(page);
+  };
+  const handlePageSizeChange = pageSize => {
+    if (externallyControlled) {
+      props.onPageSizeChange(pageSize);
+      return;
     }
-    return "Showing ".concat(visibleCount, " out of ").concat(totalItems, " ").concat(itemName).concat(totalItems !== 1 ? "s" : "");
+    paginate(1);
+    setInternalPageSize(pageSize);
   };
-  const totalPages = Math.ceil(data.length / pageSize);
-  const clonedChildren = renderChildren(children, dataForwardProp, pageData);
-  return /*#__PURE__*/_react.default.createElement(_react.default.Fragment, null, position === "below" && clonedChildren, /*#__PURE__*/_react.default.createElement("div", _extends({
-    className: (0, _classnames.default)("pagination", className)
-  }, divProps, {
-    role: "navigation"
-  }), /*#__PURE__*/_react.default.createElement("div", {
-    className: "description",
-    ref: descriptionRef
-  }, getDescription()), /*#__PURE__*/_react.default.createElement(_TablePaginationControls.default, {
-    onPageChange: paginate,
-    currentPage: currentPage,
-    totalPages: totalPages
-  }), /*#__PURE__*/_react.default.createElement(_Select.default, {
-    className: "items-per-page",
-    label: "Items per page",
-    labelClassName: "u-off-screen",
-    id: "itemsPerPage",
-    options: generatePagingOptions(pageLimits),
-    onChange: handlePageSizeChange,
-    value: pageSize
-  })), position === "above" && clonedChildren);
+  const clonedChildren = (0, _utils.renderChildren)(children, dataForwardProp, controlData);
+  const controls = /*#__PURE__*/_react.default.createElement(_TablePaginationControls.default, _extends({}, divProps, {
+    data: controlData,
+    className: className,
+    itemName: itemName,
+    description: description,
+    pageLimits: pageLimits,
+    totalItems: controlTotalItems,
+    currentPage: controlCurrentPage,
+    pageSize: controlPageSize,
+    onPageChange: handlePageChange,
+    onPageSizeChange: handlePageSizeChange
+  }));
+  return /*#__PURE__*/_react.default.createElement(_react.default.Fragment, null, position === "above" && controls, clonedChildren, position === "below" && controls);
 };
 var _default = exports.default = TablePagination;

package/dist/components/TablePagination/TablePaginationControls/TablePaginationControls.d.ts

@@ -1,16 +1,6 @@
-export type Props = {
-    /**
-     * Callback function to handle a change in page number
-     */
-    onPageChange: (pageNumber: number) => void;
-    /**
-     * The current page of the data
-     */
-    currentPage: number;
-    /**
-     * The total number of pages that exists within the data
-     */
-    totalPages: number;
-};
-declare const TablePaginationControls: ({ onPageChange, currentPage, totalPages, }: Props) => JSX.Element;
+import { HTMLAttributes } from "react";
+import { BasePaginationProps, ExternalControlProps, InternalControlProps } from "../TablePagination";
+export type AllProps = BasePaginationProps & InternalControlProps & ExternalControlProps;
+export type Props = Omit<AllProps, "externallyControlled" | "dataForwardProp" | "position"> & HTMLAttributes<HTMLDivElement>;
+declare const TablePaginationControls: ({ data, className, itemName, description, pageLimits, totalItems, currentPage, pageSize, onPageChange, onPageSizeChange, ...divProps }: Props) => JSX.Element;
 export default TablePaginationControls;

package/dist/components/TablePagination/TablePaginationControls/TablePaginationControls.js

@@ -4,18 +4,43 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _propTypes = _interopRequireDefault(require("prop-types"));
 var _Button = _interopRequireDefault(require("../../Button"));
 var _Icon = _interopRequireDefault(require("../../Icon"));
 var _Input = _interopRequireDefault(require("../../Input"));
-var _react = _interopRequireDefault(require("react"));
+var _Select = _interopRequireDefault(require("../../Select"));
+var _react = _interopRequireWildcard(require("react"));
+var _classnames = _interopRequireDefault(require("classnames"));
+var _utils = require("../utils");
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 const TablePaginationControls = _ref => {
   let {
-    onPageChange,
+    data,
+    className,
+    itemName,
+    description,
+    pageLimits,
+    totalItems,
     currentPage,
-    totalPages
+    pageSize,
+    onPageChange,
+    onPageSizeChange,
+    ...divProps
   } = _ref;
+  const descriptionRef = (0, _react.useRef)(null);
+  const isSmallScreen = (0, _utils.useFigureSmallScreen)({
+    descriptionRef
+  });
+  const totalPages = Math.ceil(totalItems / pageSize);
+  const descriptionDisplay = (0, _utils.getDescription)({
+    description,
+    data,
+    isSmallScreen,
+    totalItems,
+    itemName
+  });
   const handleDecrementPage = currentPage => {
     if (currentPage > 1) {
       onPageChange(currentPage - 1);
@@ -30,7 +55,17 @@ const TablePaginationControls = _ref => {
     const newPage = Math.min(totalPages, Math.max(1, parseInt(e.target.value)));
     onPageChange(newPage);
   };
-  return /*#__PURE__*/_react.default.createElement(_react.default.Fragment, null, /*#__PURE__*/_react.default.createElement(_Button.default, {
+  const handlePageSizeChange = e => {
+    onPageSizeChange(parseInt(e.target.value));
+  };
+  return /*#__PURE__*/_react.default.createElement("div", _extends({
+    className: (0, _classnames.default)("pagination", className)
+  }, divProps, {
+    role: "navigation"
+  }), /*#__PURE__*/_react.default.createElement("div", {
+    className: "description",
+    ref: descriptionRef
+  }, descriptionDisplay), /*#__PURE__*/_react.default.createElement(_Button.default, {
     "aria-label": "Previous page",
     className: "back",
     appearance: "base",
@@ -56,11 +91,14 @@ const TablePaginationControls = _ref => {
     onClick: () => handleIncrementPage(currentPage, totalPages)
   }, /*#__PURE__*/_react.default.createElement(_Icon.default, {
     name: "chevron-down"
-  })));
-};
-TablePaginationControls.propTypes = {
-  onPageChange: _propTypes.default.func.isRequired,
-  currentPage: _propTypes.default.number.isRequired,
-  totalPages: _propTypes.default.number.isRequired
+  })), /*#__PURE__*/_react.default.createElement(_Select.default, {
+    className: "items-per-page",
+    label: "Items per page",
+    labelClassName: "u-off-screen",
+    id: "itemsPerPage",
+    options: (0, _utils.generatePagingOptions)(pageLimits),
+    onChange: handlePageSizeChange,
+    value: pageSize
+  }));
 };
 var _default = exports.default = TablePaginationControls;

package/dist/components/TablePagination/utils.d.ts

@@ -0,0 +1,29 @@
+import { ReactElement, ReactNode, RefObject } from "react";
+/**
+ * Determine if we are working with a small screen.
+ * 'small screen' in this case is relative to the width of the description div
+ */
+export declare const figureSmallScreen: (descriptionRef: RefObject<HTMLDivElement>) => boolean;
+/**
+ * Iterate direct react child components and override the value of the prop specified by @param dataForwardProp
+ * for those child components.
+ * @param children - react node children to iterate
+ * @param dataForwardProp - the name of the prop from the children components to override
+ * @param data - actual data to be passed to the prop specified by @param dataForwardProp
+ */
+export declare const renderChildren: (children: ReactNode, dataForwardProp: string, data: unknown[]) => ReactElement<any, string | import("react").JSXElementConstructor<any>>[];
+export declare const DEFAULT_PAGE_LIMITS: number[];
+export declare const generatePagingOptions: (pageLimits: number[]) => {
+    value: number;
+    label: string;
+}[];
+export declare const getDescription: ({ description, data, isSmallScreen, totalItems, itemName, }: {
+    description: ReactNode;
+    data: unknown[];
+    isSmallScreen: boolean;
+    totalItems: number;
+    itemName: string;
+}) => string | number | true | ReactElement<any, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode>;
+export declare const useFigureSmallScreen: (args: {
+    descriptionRef: RefObject<HTMLDivElement>;
+}) => boolean;

package/dist/components/TablePagination/utils.js

@@ -0,0 +1,81 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useFigureSmallScreen = exports.renderChildren = exports.getDescription = exports.generatePagingOptions = exports.figureSmallScreen = exports.DEFAULT_PAGE_LIMITS = void 0;
+var _react = require("react");
+/**
+ * Determine if we are working with a small screen.
+ * 'small screen' in this case is relative to the width of the description div
+ */
+const figureSmallScreen = descriptionRef => {
+  const descriptionElement = descriptionRef.current;
+  if (!descriptionElement) {
+    return true;
+  }
+  return descriptionElement.getBoundingClientRect().width < 230;
+};
+
+/**
+ * Iterate direct react child components and override the value of the prop specified by @param dataForwardProp
+ * for those child components.
+ * @param children - react node children to iterate
+ * @param dataForwardProp - the name of the prop from the children components to override
+ * @param data - actual data to be passed to the prop specified by @param dataForwardProp
+ */
+exports.figureSmallScreen = figureSmallScreen;
+const renderChildren = (children, dataForwardProp, data) => {
+  return _react.Children.map(children, child => {
+    return /*#__PURE__*/(0, _react.cloneElement)(child, {
+      [dataForwardProp]: data
+    });
+  });
+};
+exports.renderChildren = renderChildren;
+const DEFAULT_PAGE_LIMITS = exports.DEFAULT_PAGE_LIMITS = [50, 100, 200];
+const generatePagingOptions = pageLimits => {
+  return pageLimits.map(limit => ({
+    value: limit,
+    label: "".concat(limit, "/page")
+  }));
+};
+exports.generatePagingOptions = generatePagingOptions;
+const getDescription = _ref => {
+  let {
+    description,
+    data,
+    isSmallScreen,
+    totalItems,
+    itemName
+  } = _ref;
+  if (description) {
+    return description;
+  }
+  const visibleCount = data.length;
+  if (isSmallScreen) {
+    return "".concat(visibleCount, " out of ").concat(totalItems);
+  }
+  if (visibleCount === totalItems && visibleCount > 1) {
+    return "Showing all ".concat(totalItems, " ").concat(itemName, "s");
+  }
+  return "Showing ".concat(visibleCount, " out of ").concat(totalItems, " ").concat(itemName).concat(totalItems !== 1 ? "s" : "");
+};
+exports.getDescription = getDescription;
+const useFigureSmallScreen = args => {
+  const {
+    descriptionRef
+  } = args;
+  const [isSmallScreen, setSmallScreen] = (0, _react.useState)(false);
+  (0, _react.useEffect)(() => {
+    const handleResize = () => {
+      setSmallScreen(figureSmallScreen(descriptionRef));
+    };
+    window.addEventListener("resize", handleResize);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+    };
+  }, [isSmallScreen, descriptionRef]);
+  return isSmallScreen;
+};
+exports.useFigureSmallScreen = useFigureSmallScreen;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonical/react-components",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "author": "Huw Wilkins <huw.wilkins@canonical.com>",