@canonical/react-components 1.6.0 → 1.7.0

package/dist/esm/components/Modal/Modal.js

@@ -0,0 +1,135 @@
+var _excluded = ["buttonRow", "children", "className", "close", "title", "shouldPropagateClickEvent"];
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], t.indexOf(o) >= 0 || {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return i; }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (e.indexOf(n) >= 0) continue; t[n] = r[n]; } return t; }
+import classNames from "classnames";
+import React, { useId, useRef, useEffect } from "react";
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Modal](https://docs.vanillaframework.io/patterns/modal/).
+ *
+ * The modal component can be used to overlay an area of the screen which can contain a prompt, dialog or interaction.
+ */
+export var Modal = _ref => {
+  var {
+      buttonRow,
+      children,
+      className,
+      close,
+      title,
+      shouldPropagateClickEvent = false
+    } = _ref,
+    wrapperProps = _objectWithoutProperties(_ref, _excluded);
+  // list of focusable selectors is based on this Stack Overflow answer:
+  // https://stackoverflow.com/a/30753870/3732840
+  var focusableElementSelectors = 'a[href]:not([tabindex="-1"]), button:not([disabled]), textarea:not([disabled]):not([tabindex="-1"]), input:not([disabled]):not([tabindex="-1"]), select:not([disabled]):not([tabindex="-1"]), area[href]:not([tabindex="-1"]), iframe:not([tabindex="-1"]), [tabindex]:not([tabindex="-1"]), [contentEditable=true]:not([tabindex="-1"])';
+  var descriptionId = useId();
+  var titleId = useId();
+  var shouldClose = useRef(false);
+  var modalRef = useRef(null);
+  var focusableModalElements = useRef(null);
+  var handleTabKey = event => {
+    if (focusableModalElements.current.length > 0) {
+      var firstElement = focusableModalElements.current[0];
+      var lastElement = focusableModalElements.current[focusableModalElements.current.length - 1];
+      if (!event.shiftKey && document.activeElement === lastElement) {
+        firstElement.focus();
+        event.preventDefault();
+      }
+      if (event.shiftKey && document.activeElement === firstElement) {
+        lastElement.focus();
+        return event.preventDefault();
+      }
+    }
+  };
+  var handleEscKey = event => {
+    if ("nativeEvent" in event && event.nativeEvent.stopImmediatePropagation) {
+      event.nativeEvent.stopImmediatePropagation();
+    } else if ("stopImmediatePropagation" in event) {
+      event.stopImmediatePropagation();
+    } else if (event.stopPropagation) {
+      event.stopPropagation();
+    }
+    if (close) {
+      close();
+    }
+  };
+  var keyListenersMap = new Map([["Escape", handleEscKey], ["Tab", handleTabKey]]);
+  useEffect(() => {
+    modalRef.current.focus();
+  }, [modalRef]);
+  useEffect(() => {
+    var _focusableModalElemen;
+    focusableModalElements.current = modalRef.current.querySelectorAll(focusableElementSelectors);
+    var focusIndex = 0;
+    // when the close button is rendered, focus on the 2nd content element and not the close btn.
+    if (close && focusableModalElements.current.length > 1) {
+      focusIndex = 1;
+    }
+    (_focusableModalElemen = focusableModalElements.current[focusIndex]) === null || _focusableModalElemen === void 0 || _focusableModalElemen.focus({
+      preventScroll: true
+    });
+  }, [close]);
+  useEffect(() => {
+    var keyDown = event => {
+      var listener = keyListenersMap.get(event.code);
+      return listener && listener(event);
+    };
+    document.addEventListener("keydown", keyDown);
+    return () => {
+      document.removeEventListener("keydown", keyDown);
+    };
+  });
+  var handleContentOnMouseDown = () => {
+    shouldClose.current = false;
+  };
+  var handleContentOnMouseUp = () => {
+    shouldClose.current = false;
+  };
+  var handleOverlayOnMouseDown = event => {
+    if (event.target === modalRef.current) {
+      shouldClose.current = true;
+    }
+  };
+  var handleClose = event => {
+    if (!shouldPropagateClickEvent) {
+      event.stopPropagation();
+    }
+    if (close) {
+      close();
+    }
+  };
+  var handleOverlayOnClick = event => {
+    if (shouldClose.current) {
+      handleClose(event);
+    }
+  };
+  return /*#__PURE__*/React.createElement("div", _extends({
+    className: classNames("p-modal", className),
+    onClick: handleOverlayOnClick,
+    onMouseDown: handleOverlayOnMouseDown
+  }, wrapperProps, {
+    ref: modalRef
+  }), /*#__PURE__*/React.createElement("section", {
+    className: "p-modal__dialog",
+    role: "dialog",
+    "aria-modal": "true",
+    "aria-labelledby": titleId,
+    "aria-describedby": descriptionId,
+    onMouseDown: handleContentOnMouseDown,
+    onMouseUp: handleContentOnMouseUp
+  }, !!title && /*#__PURE__*/React.createElement("header", {
+    className: "p-modal__header"
+  }, /*#__PURE__*/React.createElement("h2", {
+    className: "p-modal__title",
+    id: titleId
+  }, title), !!close && /*#__PURE__*/React.createElement("button", {
+    className: "p-modal__close",
+    "aria-label": "Close active modal",
+    onClick: handleClose
+  }, "Close")), /*#__PURE__*/React.createElement("div", {
+    id: descriptionId
+  }, children), !!buttonRow && /*#__PURE__*/React.createElement("footer", {
+    className: "p-modal__footer"
+  }, buttonRow)));
+};
+export default Modal;

package/dist/esm/components/Modal/Modal.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from "@storybook/react";
+import Modal from "./Modal";
+declare const meta: Meta<typeof Modal>;
+export default meta;
+type Story = StoryObj<typeof Modal>;
+export declare const Default: Story;

package/dist/esm/components/Modal/Modal.stories.js

@@ -0,0 +1,49 @@
+import { useState } from "react";
+import React from "react";
+import Modal from "./Modal";
+var Template = args => {
+  return /*#__PURE__*/React.createElement("div", {
+    style: {
+      height: "100vh",
+      position: "relative"
+    }
+  }, /*#__PURE__*/React.createElement(Modal, args));
+};
+var meta = {
+  component: Modal,
+  render: Template,
+  tags: ["autodocs"],
+  argTypes: {
+    buttonRow: {
+      control: {
+        disable: true
+      }
+    },
+    children: {
+      control: {
+        disable: true
+      }
+    }
+  }
+};
+export default meta;
+export var Default = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var [modalOpen, setModalOpen] = useState(true);
+    var closeHandler = () => setModalOpen(false);
+    return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("button", {
+      onClick: () => setModalOpen(true)
+    }, "Open modal"), modalOpen ? /*#__PURE__*/React.createElement(Modal, {
+      close: closeHandler,
+      title: "Confirm delete",
+      buttonRow: /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("button", {
+        className: "u-no-margin--bottom",
+        onClick: closeHandler
+      }, "Cancel"), /*#__PURE__*/React.createElement("button", {
+        className: "p-button--negative u-no-margin--bottom"
+      }, "Delete"))
+    }, /*#__PURE__*/React.createElement("p", null, "This will permanently delete the user \"Simon\".", /*#__PURE__*/React.createElement("br", null), "You cannot undo this action.")) : null);
+  },
+  name: "Default"
+};

package/dist/esm/components/Modal/Modal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/components/Modal/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./Modal";
+export type { Props as ModalProps } from "./Modal";

package/dist/esm/components/Modal/index.js

@@ -0,0 +1 @@
+export { default } from "./Modal";

package/dist/esm/components/ModularTable/ModularTable.d.ts

@@ -0,0 +1,105 @@
+import { ReactNode, HTMLProps } from "react";
+import { TableCellProps, TableHeaderProps, TableRowProps } from "react-table";
+import type { Column, UseTableOptions, Cell, Row, HeaderGroup } from "react-table";
+import { PropsWithSpread } from "../../types";
+export type Props<D extends Record<string, unknown>> = PropsWithSpread<{
+    /**
+     * The columns of the table.
+     */
+    columns: Column<D>[];
+    /**
+     * The data of the table.
+     */
+    data: D[];
+    /**
+     * A message to display if data is empty.
+     */
+    emptyMsg?: string;
+    /**
+     * Optional extra row to display underneath the main table content.
+     */
+    footer?: ReactNode;
+    /**
+     * Optional argument to make the tables be sortable and use the `useSortBy` plugin.
+     */
+    sortable?: boolean;
+    /**
+     * This function is used to resolve any props needed for a particular column's header cell.
+     */
+    getHeaderProps?: (header: HeaderGroup<D>) => Partial<TableHeaderProps & HTMLProps<HTMLTableHeaderCellElement>>;
+    /**
+     * This function is used to resolve any props needed for a particular row.
+     */
+    getRowProps?: (row: Row<D>) => Partial<TableRowProps & HTMLProps<HTMLTableRowElement>>;
+    /**
+     * This function is used to resolve any props needed for a particular cell.
+     */
+    getCellProps?: (cell: Cell<D>) => Partial<TableCellProps & HTMLProps<HTMLTableCellElement>>;
+    getRowId?: UseTableOptions<D>["getRowId"];
+    /**
+     * The column that the table will be sorted by (this should match a cell selector).
+     */
+    initialSortColumn?: string;
+    /**
+     * The direction of the initial sort.
+     */
+    initialSortDirection?: "ascending" | "descending";
+    /**
+     * Whether the sort by needs to be reset after each data change.
+     */
+    autoResetSortBy?: boolean;
+}, HTMLProps<HTMLTableElement>>;
+/**
+This is a [React](https://reactjs.org/) component to support many table use cases.
+ 
+ModularTable components accepts `columns` and `data` arguments in the same format as [`useTable`](https://react-table.tanstack.com/docs/api/useTable) hook of the ReactTable library.
+
+`columns` - The core columns configuration object for the entire table. https://react-table.tanstack.com/docs/api/useTable#column-options
+`data` - The data array that you want to display on the table.
+### Important note!
+Values passed to both of these params have to me memoized (for example via{" "}
+  <code>React.useMemo</code>). Memoization ensures that our data isn't recreated
+  on every render. If we didn't use <code>React.useMemo</code>, the table would
+  think it was receiving new data on every render and attempt to recalulate a
+  lot of logic every single time.
+
+#### Custom column options
+
+In addition to standard column propeties from [`useTable`](https://react-table.tanstack.com/docs/api/useTable) `ModularTable` accepts some custom properties.
+
+##### Class names
+
+Custom `className` can be used to provide a specific CSS class name that will be added to all cells in given column.
+You can also provide `getHeaderProps`, `getRowProps` and `getCellProps` to resolve additional custom props for a specific element. More on this in [`useTable - cell properties`](https://react-table.tanstack.com/docs/api/useTable#cell-properties).
+
+```js
+getCellProps={({ value, column }) => ({
+  className: `table__cell--${column.id} ${value ===  "1 minute" ? "p-heading--5" : ""}`,
+})}
+columns = {
+  Header: "Hidden on mobile",
+  accessor: "example",
+  className: "u-hide--small"
+}
+```
+
+##### Icons
+
+To show an icon in the cells of a column `getCellIcon` function should be defined. The function takes a cell data as an argument and should return one of built in icons (from the `ICONS` const), a string with a custom icon name, or `false` if no icon should be shown.
+
+The `ICONS` const contains all [the Vanilla built in icons](https://vanillaframework.io/docs/patterns/icons) such as "plus", "minus", "success", "error", etc.
+
+Product specific icons can be used as well, assuming that the product provides the necessary CSS styling and the icon follows the Vanilla naming convention `p-icon--{name}`.
+
+```js
+columns = {
+  Header: "With icons",
+  accessor: "status",
+  getCellIcon: ({ value }) => {
+    return value === "released" ? ICONS.success : false;
+  },
+};
+```
+ */
+declare function ModularTable<D extends Record<string, unknown>>({ data, columns, emptyMsg, footer, sortable, getHeaderProps, getRowProps, getCellProps, getRowId, initialSortColumn, initialSortDirection, autoResetSortBy, ...props }: Props<D>): JSX.Element;
+export default ModularTable;

package/dist/esm/components/ModularTable/ModularTable.js

@@ -0,0 +1,166 @@
+var _excluded = ["data", "columns", "emptyMsg", "footer", "sortable", "getHeaderProps", "getRowProps", "getCellProps", "getRowId", "initialSortColumn", "initialSortDirection", "autoResetSortBy"];
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], t.indexOf(o) >= 0 || {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return i; }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (e.indexOf(n) >= 0) continue; t[n] = r[n]; } return t; }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import React, { useMemo, isValidElement } from "react";
+import { useTable, useSortBy } from "react-table";
+import Table from "../Table";
+import TableRow from "../TableRow";
+import TableHeader from "../TableHeader";
+import TableCell from "../TableCell";
+import Icon from "../Icon";
+var generateCell = (cell, getCellProps) => {
+  var _cell$column$getCellI, _cell$column;
+  var hasColumnIcon = cell.column.getCellIcon;
+  var iconName = hasColumnIcon && ((_cell$column$getCellI = (_cell$column = cell.column).getCellIcon) === null || _cell$column$getCellI === void 0 ? void 0 : _cell$column$getCellI.call(_cell$column, cell));
+  return /*#__PURE__*/React.createElement(TableCell, cell.getCellProps([{
+    className: cell.column.className
+  }, {
+    className: hasColumnIcon ? "p-table__cell--icon-placeholder" : ""
+  }, _objectSpread({}, getCellProps === null || getCellProps === void 0 ? void 0 : getCellProps(cell))]), iconName && /*#__PURE__*/React.createElement(Icon, {
+    name: iconName
+  }), cell.render("Cell"));
+};
+var generateRows = (rows, prepareRow, getRowProps, getCellProps) => {
+  var tableRows = [];
+  rows.forEach(row => {
+    var _row$subRows;
+    // This function is responsible for lazily preparing a row for rendering.
+    // Any row that you intend to render in your table needs to be passed to this function before every render.
+    // see: https://react-table.tanstack.com/docs/api/useTable#instance-properties
+    prepareRow(row);
+    tableRows.push( /*#__PURE__*/React.createElement(TableRow, row.getRowProps(getRowProps === null || getRowProps === void 0 ? void 0 : getRowProps(row)), row.cells.map(cell => generateCell(cell, getCellProps))));
+    if ((_row$subRows = row.subRows) !== null && _row$subRows !== void 0 && _row$subRows.length) {
+      tableRows = tableRows.concat(generateRows(row.subRows, prepareRow, getRowProps, getCellProps));
+    }
+  });
+  return tableRows;
+};
+
+/**
+This is a [React](https://reactjs.org/) component to support many table use cases.
+ 
+ModularTable components accepts `columns` and `data` arguments in the same format as [`useTable`](https://react-table.tanstack.com/docs/api/useTable) hook of the ReactTable library.
+
+`columns` - The core columns configuration object for the entire table. https://react-table.tanstack.com/docs/api/useTable#column-options
+`data` - The data array that you want to display on the table.
+### Important note!
+Values passed to both of these params have to me memoized (for example via{" "}
+  <code>React.useMemo</code>). Memoization ensures that our data isn't recreated
+  on every render. If we didn't use <code>React.useMemo</code>, the table would
+  think it was receiving new data on every render and attempt to recalulate a
+  lot of logic every single time.
+
+#### Custom column options
+
+In addition to standard column propeties from [`useTable`](https://react-table.tanstack.com/docs/api/useTable) `ModularTable` accepts some custom properties.
+
+##### Class names
+
+Custom `className` can be used to provide a specific CSS class name that will be added to all cells in given column.
+You can also provide `getHeaderProps`, `getRowProps` and `getCellProps` to resolve additional custom props for a specific element. More on this in [`useTable - cell properties`](https://react-table.tanstack.com/docs/api/useTable#cell-properties).
+
+```js
+getCellProps={({ value, column }) => ({
+  className: `table__cell--${column.id} ${value ===  "1 minute" ? "p-heading--5" : ""}`,
+})}
+columns = {
+  Header: "Hidden on mobile",
+  accessor: "example",
+  className: "u-hide--small"
+}
+```
+
+##### Icons
+
+To show an icon in the cells of a column `getCellIcon` function should be defined. The function takes a cell data as an argument and should return one of built in icons (from the `ICONS` const), a string with a custom icon name, or `false` if no icon should be shown.
+
+The `ICONS` const contains all [the Vanilla built in icons](https://vanillaframework.io/docs/patterns/icons) such as "plus", "minus", "success", "error", etc.
+
+Product specific icons can be used as well, assuming that the product provides the necessary CSS styling and the icon follows the Vanilla naming convention `p-icon--{name}`.
+
+```js
+columns = {
+  Header: "With icons",
+  accessor: "status",
+  getCellIcon: ({ value }) => {
+    return value === "released" ? ICONS.success : false;
+  },
+};
+```
+ */
+function ModularTable(_ref) {
+  var {
+      data,
+      columns,
+      emptyMsg,
+      footer,
+      sortable,
+      getHeaderProps,
+      getRowProps,
+      getCellProps,
+      getRowId,
+      initialSortColumn,
+      initialSortDirection,
+      autoResetSortBy = false
+    } = _ref,
+    props = _objectWithoutProperties(_ref, _excluded);
+  var sortBy = useMemo(() => initialSortColumn ? [{
+    id: initialSortColumn,
+    desc: initialSortDirection === "descending"
+  }] : [], [initialSortColumn, initialSortDirection]);
+  var {
+    getTableProps,
+    getTableBodyProps,
+    headerGroups,
+    rows,
+    prepareRow
+  } = useTable({
+    columns,
+    data,
+    getRowId: getRowId || undefined,
+    initialState: {
+      sortBy
+    },
+    autoResetSortBy
+  }, sortable ? useSortBy : undefined);
+  var showEmpty = !!emptyMsg && (!rows || rows.length === 0);
+
+  // Function returns whether table can be sorted by a specific column.
+  // Returns true if sorting is enabled for the column and there is text
+  // or JSX provided for the header, otherwise returns false.
+  var isColumnSortable = column => column.canSort && ( /*#__PURE__*/isValidElement(column.Header) || (typeof column.Header === "string" || typeof column.Header === "number") && !!String(column.Header).trim());
+  var getColumnSortDirection = column => {
+    if (!isColumnSortable(column)) {
+      return undefined;
+    }
+    if (!column.isSorted) {
+      return "none";
+    }
+    return column.isSortedDesc ? "descending" : "ascending";
+  };
+  return /*#__PURE__*/React.createElement(Table, _extends({}, getTableProps(), props), /*#__PURE__*/React.createElement("thead", null, headerGroups.map((headerGroup, i) => /*#__PURE__*/React.createElement(TableRow, _extends({}, headerGroup.getHeaderGroupProps(), {
+    key: i
+  }), headerGroup.headers.map((column, j) => /*#__PURE__*/React.createElement(TableHeader, _extends({
+    key: j,
+    sort: getColumnSortDirection(column)
+  }, column.getHeaderProps([{
+    className: column.className
+  }, {
+    className: column.getCellIcon ? "p-table__cell--icon-placeholder" : ""
+  }, _objectSpread({}, getHeaderProps === null || getHeaderProps === void 0 ? void 0 : getHeaderProps(column)),
+  // Only call this if we want it to be sortable too.
+  sortable && isColumnSortable(column) ? column.getSortByToggleProps({
+    title: undefined
+  }) : {}])), column.render("Header")))))), /*#__PURE__*/React.createElement("tbody", getTableBodyProps(), generateRows(rows, prepareRow, getRowProps, getCellProps), showEmpty && /*#__PURE__*/React.createElement(TableRow, null, /*#__PURE__*/React.createElement(TableCell, {
+    colSpan: columns.length
+  }, emptyMsg)), footer && /*#__PURE__*/React.createElement(TableRow, null, /*#__PURE__*/React.createElement(TableCell, {
+    colSpan: columns.length
+  }, footer))));
+}
+export default ModularTable;

package/dist/esm/components/ModularTable/ModularTable.stories.d.ts

@@ -0,0 +1,27 @@
+import { Meta, StoryObj } from "@storybook/react";
+import ModularTable from "./ModularTable";
+declare const meta: Meta<typeof ModularTable>;
+export default meta;
+type Story = StoryObj<typeof ModularTable>;
+export declare const Default: Story;
+export declare const Empty: Story;
+export declare const Sortable: Story;
+/**
+ * Subrows can be used to group table rows under a heading that needs to appear
+at the start of the group. In the following example sorting the columns will
+sort the group rows, then sort the sub-rows, but the group header always comes first.
+ */
+export declare const Subrows: Story;
+/**
+Example below shows a basic `ModularTable` with `SummaryButton` component in the footer.
+```
+export const getSampleData = (i = 0) => [
+  { data: ++i * 100 + i },
+  { data: ++i * 100 + i },
+  { data: ++i * 100 + i },
+  { data: ++i * 100 + i },
+  { data: ++i * 100 + i },
+];
+```
+ */
+export declare const LoadMore: Story;