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

package/types/components/DataList.js.flow

@@ -8,26 +8,106 @@ import i18n from '../i18n/i18n';
 import Toaster from './Toaster';
 
 type Props = {
+  /**
+   * Name of the collection to retrieve from the API response.
+   */
   collectionName: string,
+
+  /**
+   * The default number of records to display on a single page.
+   */
   defaultPerPage?: number,
+
+  /**
+   * The default value for the search input element.
+   */
   defaultSearch?: string,
+
+  /**
+   * The default value to use for sorting the list.
+   */
   defaultSort?: string,
+
+  /**
+   * The default direction in which to sort the list.
+   */
   defaultSortDirection?: string,
+
+  /**
+   * 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?: {
     component: ComponentType<any>,
     defaults?: any,
     props?: any,
     onChange?: (filter: any) => Promise<any>
   },
+
+  /**
+   * Callback fired when the "delete" action is clicked.
+   * @param item
+   */
   onDelete?: (item: any) => Promise<any>,
+
+  /**
+   * Callback fired when the "delete all" action is clicked. This action is typically renedered in the header and will
+   * apply to every item in the list.
+   */
   onDeleteAll?: () => Promise<any>,
+
+  /**
+   * Callback fired when loading the list of items from an API. This callback is fired any time the list changes.
+   */
   onLoad: (params: any) => Promise<any>,
+
+  /**
+   * Callback fired when an item is saved via the add/edit modal.
+   */
   onSave?: (item: any) => Promise<any>,
+
+  /**
+   * The numeric list of options to allow the user to select for the number of records to display per page.
+   */
   perPageOptions?: Array<number>,
+
+  /**
+   * If provided, the <code>onLoad</code> callback will fire after a timeout of the passed number of milliseconds. This
+   * can be useful in order to show progress (file upload, download, etc) that must be retrieved from the server.
+   */
   polling?: number,
+
+  /**
+   * Callback fired when an error occurs. The passed error can take any form and is up to the consuming component to
+   * interpret. The return value should be an array of user-friendly error messages.
+   */
   resolveErrors?: (error: any) => Array<string>,
+
+  /**
+   * Used to inform the list that an external save has taken place. When set to <code>true</code>, a success toaster
+   * will display.
+   */
   saved?: boolean,
-  searchable: boolean,
+
+  /**
+   * If <code>true</code>, this component will render a search input element in the list header.
+   */
+  searchable?: boolean,
+
+  /**
+   * If provided, list properties (page number, columns, filters, etc) will be stored in the passed storage element
+   * and rehydrated each time the component is mounted. This is useful in order to persist filters, searches, and
+   * other properties when a user navigates away from the list.
+   */
   session?: {
     key: string,
     storage: typeof sessionStorage
@@ -444,7 +524,7 @@ const useDataList = (WrappedComponent: ComponentType<any>) => (
             sortColumn={this.state.sortColumn}
             sortDirection={this.state.sortDirection}
           />
-          { this.state.saved && (
+          {this.state.saved && (
             <Toaster
               onDismiss={() => this.setState({ saved: false })}
               type={Toaster.MessageTypes.positive}
@@ -457,7 +537,7 @@ const useDataList = (WrappedComponent: ComponentType<any>) => (
               />
             </Toaster>
           )}
-          { this.state.error && (
+          {this.state.error && (
             <Toaster
               onDismiss={() => this.setState({ error: false })}
               timeout={0}
@@ -563,3 +643,7 @@ export {
   SORT_ASCENDING,
   SORT_DESCENDING
 };
+
+export type {
+  Props
+};

package/types/components/DataTable.js.flow

@@ -13,45 +13,98 @@ import {
 import _ from 'underscore';
 import i18n from '../i18n/i18n';
 import ColumnResize from './ColumnResize';
-import useColumnSelector from './DataTableColumnSelector';
-import useList from './List';
+import useColumnSelector, { Props as ColumnSelectorProps } from './DataTableColumnSelector';
+import useList, { Props as ListProps } from './List';
 import './DataTable.css';
 
 import type { Action } from './List';
 
-type Column = {
-  className?: string,
-  hidden?: boolean,
-  label?: string,
-  name: string,
-  render?: (item: any) => void,
-  renderHeader?: (item: any) => void,
-  resolve?: (item: any) => void,
-  sortable: boolean
-};
+type Props = ListProps & ColumnSelectorProps & {
+  /**
+   * If <code>true</code>, the rows of the table can be expanded and collapsed.
+   */
+  expandableRows?: boolean,
 
-type Props = {
-  actions: Array<Action>,
-  className: string,
-  columns: Array<Column>,
-  expandableRows: boolean,
-  expandPanel: (item: any, activePanel: any) => Component<any>,
-  isRowSelected: (item: any) => boolean,
+  /**
+   * Function that returns JSX to render when the row for the passed item is expanded.
+   */
+  expandPanel?: (item: any, activePanel: any) => 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,
-  onClearSelected: () => void,
-  onColumnClick: (column: Column) => void,
-  onRowSelect?: (item: any)=>void,
-  onSelectAll: (items: Array<any>)=>void,
-  renderEmptyMessage: () => Element<any>,
+
+  /**
+   * Set to <code>true</code> if the list is currently loading data. If true, a loading indicator will display.
+   */
+  loading?: boolean,
+
+  /**
+   * Callback to clear the selected set of records.
+   */
+  onClearSelected?: () => void,
+
+  /**
+   * Callback fired when the passed column is clicked.
+   */
+  onColumnClick?: (column: Column) => 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 in the table header is clicked.
+   */
+  onSelectAll?: (items: Array<any>) => void,
+
+  /**
+   * A function that returns a JSX element to render when the list is empty.
+   */
+  renderEmptyMessage?: () => Element<any>,
+
+  /**
+   * A function that returns a custom JSX element to render when the list is empty. This element will replace the
+   * entire single row of the table.
+   */
   renderEmptyRow?: () => void,
+
+  /**
+   * A function that returns a custom JSX element to render for the passed item. This element will replace the entire
+   * table row.
+   */
   renderItem?: (item: any, index: number, children?: any) => 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,
+
+  /**
+   * Name of the current sort column.
+   */
   sortColumn?: string,
+
+  /**
+   * Current sort direction (ascending or descending).
+   */
   sortDirection?: string,
-  t: (key: string) => string,
-  tableProps: any,
-  selectable?: boolean,
-  selectedRows: Array<{id: number}>,
+
+  /**
+   * Customization props for the
+   * <a target="_blank" href="https://react.semantic-ui.com/collections/table/"><code>Table</code></a>
+   * component.
+   */
+  tableProps?: any
 };
 
 type State = {
@@ -596,7 +649,6 @@ DataTable.defaultProps = {
   renderSearch: undefined,
   renderItem: undefined,
   showRecordCount: false,
-  selectedRows: [],
   sortColumn: undefined,
   sortDirection: undefined,
 };
@@ -604,5 +656,5 @@ DataTable.defaultProps = {
 export default useColumnSelector(useList(DataTable));
 
 export type {
-  Column
+  Props
 };

package/types/components/DataTableColumnSelector.js.flow

@@ -5,14 +5,45 @@ import React, { Component, type ComponentType, type Element } from 'react';
 import { Checkbox, Dropdown, Icon } from 'semantic-ui-react';
 import _ from 'underscore';
 import Draggable from './Draggable';
+import type { Props as ListProps } from './List';
 import './DataTableColumnSelector.css';
 
-import type { Column } from './DataTable';
+type Column = {
+  className?: string,
+  hidden?: boolean,
+  label?: string,
+  name: string,
+  render?: (item: any) => Element<any>,
+  renderHeader?: (item: any) => Element<any>,
+  resolve?: (item: any) => any,
+  sortable: boolean
+};
 
-type Props = {
-  className: string,
-  columns: Array<Column>,
-  renderListHeader?: () => Element<any>
+type Props = ListProps & {
+  /**
+   * CSS class name to append to the wrapped component.
+   */
+  className?: string,
+
+  /**
+   * An array of columns to display within the <code>Table</code>.
+   * <br />
+   * <br />
+   *
+   * If only a <code>name</code> attribute is provided, the value for each record will be pulled from the item property
+   * matching that name.
+   * <br />
+   * <br />
+   *
+   * If a <code>resolve</code> callback is provided, the item will be passed to the function and the return value will
+   * display as the property value.
+   * <br />
+   * <br />
+   *
+   * If a <code>render</code> callback is provided, the item will be passed to the function and the return JSX
+   * will display as the property value.
+   */
+  columns: Array<Column>
 };
 
 type State = {
@@ -165,3 +196,8 @@ const useColumnSelector = (WrappedComponent: ComponentType<any>) => (
 );
 
 export default useColumnSelector;
+
+export type {
+  Column,
+  Props
+};

package/types/components/DataView.js.flow

@@ -19,7 +19,7 @@ import ModalContext from '../context/ModalContext';
 import useDataList, { SORT_ASCENDING, SORT_DESCENDING } from './DataList';
 import './DataView.css';
 
-import type { Column } from './DataTable';
+import type { Column } from './DataTableColumnSelector';
 
 type Sort = {
   label: string,

package/types/components/EditModal.js.flow

@@ -14,13 +14,33 @@ import i18n from '../i18n/i18n';
 import './EditModal.css';
 
 type Props = EditContainerProps & {
+  /**
+   * The form component to render.
+   */
   component: ComponentType<any>,
+
+  /**
+   * Callback fired when the close button is clicked.
+   */
   onClose: () => void,
+
+  /**
+   * Callback fired when the save button is clicked.
+   */
   onSave: () => Promise<any>,
+
+  /**
+   * If <code>true</code>, a loading indicator will display.
+   */
   showLoading: boolean
 };
 
-const EditModal = (props: Props) => {
+/**
+ * The <code>EditModal</code> component can be used to edit the details of a single record within a modal view. This
+ * component uses the <code>EditContainer</code> higher-order component to facilitate all of the editing functionality.
+ * This component is responsible for rendering the container in which the editable form is rendered.
+ */
+const EditModal = useEditContainer((props: Props) => {
   const OuterComponent = props.component;
 
   const [showToaster, setShowToaster] = useState(false);
@@ -89,10 +109,10 @@ const EditModal = (props: Props) => {
       </Modal.Actions>
     </OuterComponent>
   );
-};
+});
 
 EditModal.defaultProps = {
   showLoading: true
 };
 
-export default useEditContainer(EditModal);
+export default EditModal;

package/types/components/EditPage.js.flow

@@ -18,11 +18,34 @@ import i18n from '../i18n/i18n';
 import './EditPage.css';
 
 type Props = EditContainerProps & {
+  /**
+   * CSS class name to append to the container <code>div</code> element.
+   */
   className?: string,
+
+  /**
+   * The form component to render.
+   */
   component: ComponentType<any>,
+
+  /**
+   * If provided, the passed menu will render as tabs at the top of the page.
+   */
   menu?: MenuProps,
+
+  /**
+   * Callback fired when the close button is clicked.
+   */
   onClose: () => void,
+
+  /**
+   * Callback fired when the save button is clicked.
+   */
   onSave: () => Promise<any>,
+
+  /**
+   * If <code>true</code>, a loading indicator will display.
+   */
   showLoading: boolean
 };
 
@@ -31,7 +54,12 @@ type State = {
   showToaster: boolean
 };
 
-class EditPage extends Component<Props, State> {
+/**
+ * The <code>EditPage</code> component can be used to edit the details of a single record within a page view. This
+ * component uses the <code>EditContainer</code> higher-order component to facilitate all of the editing functionality.
+ * This component is responsible for rendering the container in which the editable form is rendered.
+ */
+class EditPageClass extends Component<Props, State> {
   static defaultProps: any;
 
   /**
@@ -238,11 +266,12 @@ class EditPage extends Component<Props, State> {
   }
 }
 
-EditPage.defaultProps = {
+EditPageClass.defaultProps = {
   showLoading: true
 };
 
-export default useEditContainer(EditPage);
+const EditPage = useEditContainer(EditPageClass);
+export default EditPage;
 
 export type EditPageProps = EditContainerProps & {
   currentTab: string

package/types/components/EmbeddedList.js.flow

@@ -4,45 +4,27 @@ import React, { Component, type ComponentType } from 'react';
 import { Table } from 'semantic-ui-react';
 import uuid from 'react-uuid';
 import _ from 'underscore';
-import DataTable from './DataTable';
+import DataTable, { type Props as DataTableProps } from './DataTable';
 import Draggable from './Draggable';
 import './EmbeddedList.css';
 
-import type { Action } from './List';
-import type { Column } from './DataTable';
+import type { Column, Props as ColumnSelectorProps } from './DataTableColumnSelector';
 
-type ListButton = {
-  render: () => ComponentType<any>
-};
-
-type Props = {
-  actions: Array<Action>,
-  addButton?: {
-    location: string,
-    color: string
-  },
-  buttons?: Array<ListButton>,
-  className?: string,
-  columns: Array<Column>,
-  configurable: boolean,
+type Props = DataTableProps & ColumnSelectorProps & {
+  /**
+   * The name of the default sort column.
+   */
   defaultSort?: string,
+
+  /**
+   * The default direction to sort the list (ascending vs. descending).
+   */
   defaultSortDirection?: string,
-  items: Array<any>,
-  modal?: {
-    component: ComponentType<any>,
-    props: any,
-    state: any
-  },
-  onCopy?: (item: any) => any,
-  onDelete: (item: any) => void,
-  onDrag?: (dragIndex: number, hoverIndex: number) => void,
-  onSave?: (item: any) => void,
-  renderDeleteModal?: ({ selectedItem: any, onCancel: () => void, onConfirm: () => void }) => void,
-  renderEmptyRow?: () => void,
-  selectable: boolean,
-  onRowSelect: (Array<{id: number}>),
-  selectedRows: Array<{id: number}>,
-  showRecordCount: boolean,
+
+  /**
+   * Callback fired when a table row is dragged.
+   */
+  onDrag?: (dragIndex: number, hoverIndex: number) => void
 };
 
 type State = {
@@ -55,8 +37,8 @@ const SORT_ASCENDING = 'ascending';
 const SORT_DESCENDING = 'descending';
 
 /**
- * The EmbeddedList component can be used to display a collection of records that live within a parent object. This is
- * especially useful when the collection is to be saved at the same time as the parent.
+ * The <code>EmbeddedList</code> component can be used to display a collection of records that live within a parent
+ * object. This is especially useful when the collection is to be saved at the same time as the parent.
  */
 class EmbeddedList extends Component<Props, State> {
   static defaultProps: any;

package/types/components/FileUpload.js.flow

@@ -8,8 +8,19 @@ import i18n from '../i18n/i18n';
 import './FileUpload.css';
 
 type Props = {
+  /**
+   * A list of file types to include
+   */
   fileTypes?: Array<string>,
+
+  /**
+   * The maximum size for a single file
+   */
   maxSize?: number,
+
+  /**
+   * Call back for when files are added
+   */
   onFilesAdded: (files: Array<File>) => void,
 };
 
@@ -23,6 +34,10 @@ type FileEvent = {
   target: HTMLInputElement
 };
 
+/**
+ * The <code>FileUpload</code> component renders a dropzone and allows a user to drop or select one or more files
+ * from their local file system. Optionally, the files can be limited by size or type.
+ */
 class FileUpload extends Component<Props, State> {
   fileInput: any;
   filePattern: any;

package/types/components/FileUploadModal.js.flow

@@ -17,13 +17,44 @@ import ModalContext from '../context/ModalContext';
 import Toaster from './Toaster';
 
 type Props = {
+  /**
+   * Content to display on the button used to open the modal
+   */
   button: string,
+
+  /**
+   * Determines if the component should render a button as a trigger for the modal
+   */
   includeButton?: boolean,
+
+  /**
+   * Component to render within the modal
+   */
   itemComponent: ComponentType<any>,
-  onAddFile: (file: File) => any,
+
+  /**
+   * Callback fired when a file is added
+   */
+  onAddFile: (file: File) => void,
+
+  /**
+   * Callback fired when the close button is clicked
+   */
   onClose?: () => void,
+
+  /**
+   * Callback fired when the save button is clicked
+   */
   onSave: (items: Array<any>) => Promise<any>,
+
+  /**
+   * An object with keys containing the names of properties that are required
+   */
   required: { [string]: string },
+
+  /**
+   * Title value to display in the modal header
+   */
   title?: string
 };
 
@@ -35,9 +66,11 @@ type State = {
 
 const LIST_DELIMITER = ', ';
 
+/**
+ * The <code>FileUploadModal</code> is a convenience wrapper for the <code>FileUpload</code> component, allowing
+ * it to render in a modal.
+ */
 class FileUploadModal extends Component<Props, State> {
-  static defaultProps: any;
-
   /**
    * Constructs a new FileUploadModal component.
    *

package/types/components/ItemCollection.js.flow

@@ -6,27 +6,64 @@ import uuid from 'react-uuid';
 import { Loader } from 'semantic-ui-react';
 import _ from 'underscore';
 import i18n from '../i18n/i18n';
-import Items from './Items';
+import Items, { type Props as ItemsProps } from './Items';
 import './ItemCollection.css';
 
-type Props = {
+type Props = ItemsProps & {
+  /**
+   * Appends the passed <code>className</code> and passes it to the <code>Items</code> component.
+   */
   className?: string,
+
+  /**
+   * The DOM element responsible for infinite scrolling. If no context is provided, the document <code>body</code>
+   * will be assumed.
+   */
   context: {
     current: HTMLElement
   },
-  items: Array<any>,
+
+  /**
+   * If <code>true</code>, the list will display a loading indicator.
+   */
   loading?: boolean,
+
+  /**
+   * Callback fired when the bottom of the scroll container is reached.
+   */
   onBottomReached?: (page: number) => void,
-  onDelete: (item: any) => void,
+
+  /**
+   * Callback fired when the delete action is clicked.
+   */
+  onDelete?: (item: any) => void,
+
+  /**
+   * Callback fired when a new record is added to the list.
+   */
   onSave?: (item: any) => void,
-  perPage: number,
-  scrollOffset: number
+
+  /**
+   * The number of records to display on a single page.
+   */
+  perPage?: number,
+
+  /**
+   * The number of pixels from the bottom of the scroll container the <code>onBottomReached</code> callback
+   * should fire.
+   */
+  scrollOffset?: number
 };
 
 type State = {
   page: number
 };
 
+/**
+ * An <code>ItemCollection</code> component can be used to render a list of records stored on an object in memory. This
+ * component is responsible for handling infinite scroll and rendering the <code>Items</code> component, which handles
+ * the presentation.
+ */
 class ItemCollection extends Component<Props, State> {
   static defaultProps: any;