@performant-software/semantic-components 1.0.2 → 1.0.3-beta.1

package/types/components/ItemList.js.flow

@@ -1,16 +1,11 @@
 // @flow
 
 import React, { useCallback, useEffect, useMemo } from 'react';
-import { Button, Dimmer, Loader } from 'semantic-ui-react';
+import { Dimmer, Loader } from 'semantic-ui-react';
 import _ from 'underscore';
 import i18n from '../i18n/i18n';
-import Items from './Items';
-import useDataList, { SORT_ASCENDING } from './DataList';
-
-type ListButton = {
-  ...typeof Button,
-  accept: () => boolean
-};
+import Items, { type ItemsProps } from './Items';
+import useDataList, { SORT_ASCENDING, type Props as DataListProps } from './DataList';
 
 type Sort = {
   key: any,
@@ -19,30 +14,36 @@ type Sort = {
   direction: ?string
 };
 
-type Props = {
-  buttons: Array<ListButton>,
-  isRowSelected: (item: any) => boolean,
-  items: Array<any>,
-  loading?: boolean,
-  page: number,
-  onRowSelect: (item: any) => void,
+type Props = DataListProps & ItemsProps & {
+  /**
+   * Callback fired when the sort dropdown is changed. This prop is provided by the <code>DataList</code>
+   * higher-order component.
+   */
   onSort: (column: string, direction: ?string, page?: number) => void,
-  selectable?: boolean,
+
+  /**
+   * An array of sort attributes to apply to the list. The values provided will display in a dropdown in the
+   * list header.
+   */
   sort?: Array<Sort>,
+
+  /**
+   * Name of the current sort column.
+   */
   sortColumn?: string,
+
+  /**
+   * Current sort direction (ascending or descending).
+   */
   sortDirection?: string
 };
 
 /**
- * An ItemList component can be used to render a list of records returned from an API. Under the hood, the DataList
- * component handles calling the API, storing the records, filters, etc, and the Items component handles the
- * presentation.
- *
- * @param props
- *
- * @returns {*}
+ * An <code>ItemList</code> component can be used to render a list of records returned from an API. Under the
+ * hood, the <code>DataList</code> component handles calling the API, storing the records, filters, etc, and
+ * the <code>Items</code> component handles the presentation.
  */
-const ItemList = (props: Props) => {
+const ItemList = useDataList((props: Props) => {
   useEffect(() => {
     const { page } = props;
 
@@ -112,15 +113,11 @@ const ItemList = (props: Props) => {
       />
     </>
   );
-};
+});
 
 ItemList.defaultProps = {
   filters: {},
-  onCopy: undefined,
-  onSort: () => {},
-  renderDeleteModal: undefined,
-  renderEmptyRow: undefined,
   searchable: true,
 };
 
-export default useDataList(ItemList);
+export default ItemList;

package/types/components/Items.js.flow

@@ -20,30 +20,95 @@ import './Items.css';
 import type { Props as ListProps } from './List';
 
 type Props = ListProps & {
-  children: Element<any>,
-  className: string,
+  /**
+   * Child elements to append below the list content.
+   */
+  children?: Element<any>,
+
+  /**
+   * Callback returning <code>true</code> if the row for the passed item is selected.
+   */
   isRowSelected?: (item: any) => boolean,
+
+  /**
+   * An array of objects to render as rows in the list.
+   */
   items: Array<any>,
-  loading: boolean,
+
+  /**
+   * Callback fired when a table row is dragged
+   */
   onDrag?: (dragIndex: number, hoverIndex: number) => void,
+
+  /**
+   * Callback fired when the passed item is selected. This callback is <i>only</i> fired if the <code>selectable</code>
+   * prop is passed as <code>true</code>.
+   */
   onRowSelect?: (item: any) => void,
+
+  /**
+   * Callback fired when the select all checkbox is checked.
+   */
   onSelectAllRows?: (items: Array<any>) => void,
+
+  /**
+   * A function that returns a JSX element to render as additional card content.
+   */
   renderAdditionalContent?: (item: any) => Element<any>,
+
+  /**
+   * A function that returns a JSX element to render as the card description.
+   * See Semantic UI <a href="https://react.semantic-ui.com/views/card/">Card</a>.
+   */
   renderDescription?: (item: any) => Element<any>,
-  renderEmptyList: () => Element<any>,
+
+  /**
+   * A function that returns a JSX element to render when the list has no items.
+   */
+  renderEmptyList?: () => Element<any>,
+
+  /**
+   * A function that returns a JSX element to render as the card extra content.
+   * See Semantic UI <a href="https://react.semantic-ui.com/views/card/">Card</a>.
+   */
   renderExtra?: (item: any) => Element<any>,
+
+  /**
+   * A function that returns a JSX element to render as the card header.
+   * See Semantic UI <a href="https://react.semantic-ui.com/views/card/">Card</a>.
+   */
   renderHeader?: (item: any) => Element<any>,
+
+  /**
+   * A function that returns a JSX element to render as the card image.
+   * See Semantic UI <a href="https://react.semantic-ui.com/views/card/">Card</a>.
+   */
   renderImage?: (item: any) => Element<any>,
+
+  /**
+   * A function that returns a JSX element to render as the card meta.
+   * See Semantic UI <a href="https://react.semantic-ui.com/views/card/">Card</a>.
+   */
   renderMeta?: (item: any) => Element<any>,
+
+  /**
+   * If <code>true</code>, a selection box will display for each row.
+   */
   selectable?: boolean,
+
+  /**
+   * Toggles between list view and grid view. This prop is provided by the <code>ItemsToggle</code> higher-order
+   * component.
+   */
   view: number
 };
 
 /**
- * The Items component is used as the presentation for a list of records. The component renders both a list
- * (see Semantic-UI List) and grid (see Semantic-UI Card) views.
+ * The <code>Items</code> component is used as the presentation for a list of records. The component renders
+ * both a <a href="https://react.semantic-ui.com/elements/list/" target="_blank">List</a> and
+ * <a href="https://react.semantic-ui.com/views/card/" target="_blank">Card</a> views.
  */
-class Items extends Component<Props, {}> {
+class ItemsClass extends Component<Props, {}> {
   static defaultProps: any;
 
   /**
@@ -360,8 +425,13 @@ class Items extends Component<Props, {}> {
   }
 }
 
-Items.defaultProps = {
+ItemsClass.defaultProps = {
   actions: []
 };
 
-export default useItemsToggle(useList(Items));
+const Items = useItemsToggle(useList(ItemsClass));
+export default Items;
+
+export type {
+  Props
+};

package/types/components/List.js.flow

@@ -37,8 +37,17 @@ type ListButton = {
 };
 
 type Props = {
-  actions: Array<Action>,
-  addButton: {
+  /**
+   * A list of actions to render for each element in the row. Actions with the names "edit" and "delete" will be
+   * handled specially by the <code>List</code> higher-order component.
+   */
+  actions?: Array<Action>,
+
+  /**
+   * If provided, a button will display in the list header allowing the addition of items to the list. When clicked,
+   * the <code>modal</code> prop will be rendered.
+   */
+  addButton?: {
     basic: boolean,
     color: string,
     content?: string,
@@ -47,15 +56,50 @@ type Props = {
     onClick?: () => void,
     secondary?: boolean
   },
-  buttons: Array<ListButton>,
-  count: number,
-  className: string,
-  configurable: boolean,
+
+  /**
+   * A list of arbitrary buttons to the display in the list header. All actions will be handled by the consuming
+   * component.
+   * <br />
+   * <br />
+   *
+   * In addition to the props listed here for each button, buttons will also accept any of the Semantic UI
+   * <a href="https://react.semantic-ui.com/elements/button/" target="_blank">Button</a> props.
+   */
+  buttons?: Array<ListButton>,
+
+  /**
+   * The number of total records in the list (not just the current page).
+   */
+  count?: number,
+
+  /**
+   * CSS class name to append to the <code>div</code> container.
+   */
+  className?: string,
+
+  /**
+   * If provided, a "delete all" button will be rendered in the list header.
+   */
   deleteButton?: {
     color: string,
     location: string,
     onClick?: () => void
   },
+
+  /**
+   * If provided, the passed <code>component</code> will be rendered when the filter button is clicked.
+   * <br />
+   * <br />
+   *
+   * Values passed in the <code>defaults</code> and <code>props</code> properties will be made available in the
+   * passed component.
+   * <br />
+   * <br />
+   *
+   * The <code>onChange</code> callback will fire when the filters are modified. This action will also reload the list,
+   * passing the new filters the <code>onLoad</code> callback.
+   */
   filters?: {
     active: boolean,
     component: Component<{}>,
@@ -63,32 +107,94 @@ type Props = {
     state?: any,
     onChange: (params: any) => Promise<any>
   },
-  items: ?Array<any>,
-  loading?: boolean,
+
+  /**
+   * If provided, the passed modal will be rendered when the "add" button is clicked.
+   */
   modal?: {
-    component: Element<any>,
+    component: ComponentType<any>,
     props: any,
     state: any
   },
-  page: number,
-  pages: number,
+
+  /**
+   * If provided, this callback is fired when the "copy" action is clicked for an item. The consuming component
+   * should generate a copy of the selected item and return that value. The return value is then set at the
+   * current item in the edit modal.
+   */
   onCopy?: (item: any) => any,
-  onDelete: (item: any) => void,
+
+  /**
+   * Callback fired when the "delete" action is clicked for an item.
+   */
+  onDelete?: (item: any) => void,
+
+  /**
+   * Callback fired when the delete all button is clicked. This prop expects a Promise as the return value.
+   */
   onDeleteAll?: () => Promise<any>,
-  onPageChange: () => void,
-  onPerPageChange: () => void,
-  onSave: (item: any) => Promise<any>,
-  onSelectAll?: (items: Array<any>) => void,
-  perPage: number,
-  perPageOptions: Array<number>,
+
+  /**
+   * Callback fired when the page is changed via the pagination component.
+   */
+  onPageChange?: () => void,
+
+  /**
+   * Callback fired when the per page value is changed.
+   */
+  onPerPageChange?: () => void,
+
+  /**
+   * Callback fired when the save button is clicked in the add/edit modal. This function expects a Promise as the
+   * return value.
+   */
+  onSave?: (item: any) => Promise<any>,
+
+  /**
+   * Current page number.
+   */
+  page?: number,
+
+  /**
+   * Number of pages in the list.
+   */
+  pages?: number,
+
+  /**
+   * The number of records to display per page.
+   */
+  perPage?: number,
+
+  /**
+   * The options to display in the dropdown for the per page selector.
+   */
+  perPageOptions?: Array<number>,
+
+  /**
+   * Custom render function for the modal that appears on the "delete" action.
+   */
   renderDeleteModal?: ({ selectedItem: any, onCancel: () => void, onConfirm: () => void }) => Element<any>,
-  renderEmptyRow?: () => void,
-  renderItem?: (item: any, index: number, children?: any) => Element<any>,
+
+  /**
+   * If provided, this function will return a JSX element that will prepend to the list header.
+   */
   renderListHeader?: () => ?Element<any>,
+
+  /**
+   * If provided, this function will return a JSX element that will replace the default search input.
+   */
   renderSearch?: () => Element<any>,
+
+  /**
+   * If set to <code>true</code>, checkboxes will render as the first table column, allowing each row to be selectable.
+   * The consuming component is responsible for tracking the selected items.
+   */
   selectable?: boolean,
-  showRecordCount: boolean,
-  t: (key: string) => string
+
+  /**
+   * If <code>true</code>, the total number of records will display in the list header.
+   */
+  showRecordCount?: boolean
 };
 
 type State = {
@@ -122,8 +228,6 @@ const useList = (WrappedComponent: ComponentType<any>) => (
       buttons: [],
       className: '',
       filters: undefined,
-      items: [],
-      loading: false,
       modal: undefined,
       page: 1,
       pages: 1,
@@ -131,9 +235,7 @@ const useList = (WrappedComponent: ComponentType<any>) => (
       onCopy: undefined,
       onPageChange: () => {},
       renderDeleteModal: undefined,
-      renderEmptyRow: undefined,
       renderSearch: undefined,
-      renderItem: undefined,
       sortColumn: undefined,
       sortDirection: undefined
     };

package/types/components/ListTable.js.flow

@@ -4,23 +4,61 @@ import { Hooks, Object as ObjectUtils } from '@performant-software/shared-compon
 import React, { useEffect } from 'react';
 import _ from 'underscore';
 import DataTable from './DataTable';
-import useDataList, { SORT_ASCENDING, SORT_DESCENDING } from './DataList';
+import type { Props as DataTableProps } from './DataTable';
+import useDataList, { SORT_ASCENDING, SORT_DESCENDING, type Props as DataListProps } from './DataList';
 import './ListTable.css';
 
-import type { Column } from './DataTable';
+type Props = DataListProps & DataTableProps & {
+  /**
+   * If true, columns can be shown/hidden by the user.
+   */
+  configurable?: boolean,
 
-type Props = {
-  columns: Array<Column>,
+  /**
+   * The name of the default sort column.
+   */
   defaultSort?: string,
+
+  /**
+   * The default direction to sort the list (ascending vs. descending).
+   */
   defaultSortDirection?: string,
-  page: number,
-  onSort: (sortColumn: string, sortDirection: string, page?: number) => void,
-  onInit: (page?: number) => void,
-  sortColumn: string,
-  sortDirection: string
+
+  /**
+   * Callback supplied by the <code>DataList</code> higher-order component which can be used to initialize the list.
+   */
+  onInit?: (page?: number) => void,
+
+  /**
+   * Callback supplied by the <code>DataList</code> higher-order component which can be used to sort the list.
+   */
+  onSort?: (sortColumn: string, sortDirection: string, page?: number) => void,
+
+  /**
+   * Current sort column supplied by the <code>DataList</code> higher-order component.
+   */
+  sortColumn?: string,
+
+  /**
+   * Current sort direction supplied by the <code>DataList</code> higher-order component.
+   */
+  sortDirection?: string,
+
+  /**
+   * Customization props for the
+   * <a target="_blank" href="https://react.semantic-ui.com/collections/table/"><code>Table</code></a>
+   * component.
+   */
+  tableProps?: any
 };
 
-const ListTable = (props: Props) => {
+/**
+ * The <code>ListTable</code> component renders a list which has the ability to load, save, and delete records from
+ * an API (via the <code>DataList</code> higher-order component). This component will integrate seamlessly with a
+ * back-end implementing the <code>resource-api</code>. See the
+ * <a href="https://github.com/performant-software/resource-api">GitHub page</a> for more details.
+ */
+const ListTable = useDataList((props: Props) => {
   const prevColumns = Hooks.usePrevious(props.columns);
 
   /**
@@ -82,17 +120,14 @@ const ListTable = (props: Props) => {
       onColumnClick={onColumnClick.bind(this)}
     />
   );
-};
+});
 
 ListTable.defaultProps = {
   configurable: true,
-  onCopy: undefined,
-  renderDeleteModal: undefined,
-  renderEmptyRow: undefined,
   tableProps: {
     celled: true,
     sortable: true
   }
 };
 
-export default useDataList(ListTable);
+export default ListTable;