chore(FDS-247): [DOCS] - add docs for Cascara components

docs/src/lib/MDX_COMPONENTS.js

@@ -5,13 +5,18 @@
 // until there is a better way to import static data dynamically in Nextjs
 
 import {
+  ActionStack,
   Admin,
   Button,
   Chat,
   Dashboard,
   Form,
   JsonPlaceholder,
+  List,
+  Pagination,
   Table,
+  Tabs,
+  usePaginationState,
 } from '@espressive/cascara';
 
 import {
@@ -41,6 +46,7 @@ const docsComponents = {
 };
 
 const cascaraComponents = {
+  ActionStack: (props) => <ActionStack {...props} />,
   Admin: (props) => <Admin {...props} />,
   Button: (props) => <Button {...props} />,
   Chat: (props) => (
@@ -51,7 +57,10 @@ const cascaraComponents = {
   Dashboard: (props) => <Dashboard {...props} />,
   Form: (props) => <Form {...props} />,
   JsonPlaceholder: (props) => <JsonPlaceholder {...props} />,
+  List: (props) => <List {...props} />,
+  Pagination: (props) => <Pagination {...props} />,
   Table: (props) => <Table {...props} />,
+  Tabs: (props) => <Tabs {...props} />,
 };
 
 const privateComponents = {
@@ -74,6 +83,7 @@ const MDX_COMPONENTS = {
   ...cascaraComponents,
   ...docsComponents,
   ...privateComponents,
+  usePaginationState,
 };
 
 export default MDX_COMPONENTS;

packages/cascara/src/ui/ActionStack/ActionStack.doc.mdx

@@ -0,0 +1,70 @@
+---
+title: ActionStack
+propTable: ActionStack.js
+status: 'ALPHA'
+---
+
+# Public API
+
+WARNING! This is an alpha release so we can try to get this code in and working to kick the tires.
+
+## `actions`
+
+This is an array of objects used to tell ActionStack what to display. The `label` prop is the text for clickable element. The `onClick` prop is the click handler.
+
+```jsx
+---
+title: ActionStack with Actions
+---
+<ActionStack
+  actions={[
+    {
+      "label": "Action 1",
+      onClick: console.log
+    },
+    {
+      "label": "Action 2",
+      onClick: console.log
+    },
+    {
+      "label": "Action 3",
+      onClick: console.log
+    },
+    {
+      "label": "Action 4",
+      onClick: console.log
+    },
+  ]}
+/>
+```
+
+## `dropdownIndex`
+
+A number specifying the index at which `actions` start to appear as dropdown items. The following example would render actions 1 and 2 as buttons and actions 4 and 4 as a dropdown items.
+
+```jsx
+---
+title: ActionStack with dropdownIndex
+---
+<ActionStack
+  actions={[
+    {
+      "label": "Action 1",
+      onClick: console.log
+    },
+    {
+      "label": "Action 2",
+      onClick: console.log
+    },
+    {
+      "label": "Action 3",
+      onClick: console.log
+    },
+    {
+      "label": "Action 4",
+      onClick: console.log
+    },
+  ]}
+  dropdownIndex={2}
+/>
+```

packages/cascara/src/ui/ActionStack/ActionStack.js

@@ -6,7 +6,9 @@ import DropdownStack from './DropdownStack';
 import { JsonPlaceholder } from '@espressive/cascara';
 
 const propTypes = {
+  /** An array of objects describing the actions */
   actions: pt.arrayOf(ACTION_SHAPE),
+  /** A number specifying the index at which `actions` start to appear as dropdown items */
   dropdownIndex: pt.number,
 };
 

packages/cascara/src/ui/Form/Form.js

@@ -30,36 +30,41 @@ const actionModuleOptions = Object.keys(availableActionModules);
 const dataModuleOptions = Object.keys(formDataModules);
 
 const propTypes = {
-  // Actions will be appended to each row, they'll appear as buttons.
+  /** Actions will be appended to each row, they'll appear as buttons. */
   actions: pt.shape({
+    /** An array of action objects */
     modules: pt.arrayOf(
       pt.shape({
+        /** A string that specifies the type of module to use */
         module: pt.oneOf(actionModuleOptions).isRequired,
       })
     ),
   }),
 
-  // An object of modules to display.
-  //
-  // Every parameter in this object can potentially be rendered in the form.
+  /**
+   * An object of modules to display.
+   *
+   * Every parameter in this object can potentially be rendered in the form.
+   */
   data: pt.shape({}),
 
-  // Here you can describe each of the visible columns in your table.
+  /** Here you can describe each of the visible columns in your table. */
   dataDisplay: pt.arrayOf(
     pt.shape({
       module: pt.oneOf(dataModuleOptions).isRequired,
     })
   ),
 
-  // a form can be editable
+  /** a form can be editable */
   isEditable: pt.bool,
 
-  // A form can start in an editing state
+  /** A form can start in an editing state */
   isInitialEditing: pt.bool,
 
+  /** Specifies if a loading state is show */
   isLoading: pt.bool,
 
-  // A form can emit events on every action
+  /** A form can emit events on every action*/
   onAction: pt.func,
 };
 

packages/cascara/src/ui/List/List.doc.mdx

@@ -0,0 +1,56 @@
+---
+title: List
+propTable: List.js
+status: 'ALPHA'
+---
+
+# Public API
+
+WARNING! This is an alpha release so we can try to get this code in and working to kick the tires.
+
+## `data`
+
+This is an array of objects used to tell List what to display.
+
+```jsx
+---
+title: List that displays an avatar, name and description
+---
+<List
+  data={[
+  {
+    pre: (
+      <img
+        alt='avatar'
+        className='ui avatar image'
+        src='https://i.pravatar.cc/150?img=1'
+      />
+    ),
+    label: 'Jack Wilshere',
+    description: 'Central Attacking Midfielder',
+  },
+  {
+    pre: (
+      <img
+        alt='avatar'
+        className='ui avatar image'
+        src='https://i.pravatar.cc/150?img=2'
+      />
+    ),
+    label: 'Carlos Vela',
+    // description: 'Central Forward',
+  },
+  {
+    pre: (
+      <img
+        alt='avatar'
+        className='ui avatar image'
+        src='https://i.pravatar.cc/150?img=3'
+      />
+    ),
+    label: 'Hector Bellerin',
+    description: 'Right Back',
+  },
+]}
+/>
+```

packages/cascara/src/ui/List/List.js

@@ -5,6 +5,7 @@ import { Composite, useCompositeState } from 'reakit/Composite';
 import styles from './List.module.scss';
 
 const propTypes = {
+  /** This is an array of objects used to tell List what to display */
   data: pt.arrayOf(pt.shape(listItemPropTypes)),
 };
 

packages/cascara/src/ui/Pagination/Pagination.doc.mdx

@@ -0,0 +1,51 @@
+---
+title: Pagination
+propTable: Pagination.js
+status: 'ALPHA'
+---
+
+# Public API
+
+WARNING! This is an alpha release so we can try to get this code in and working to kick the tires.
+
+## Loading
+
+When defining no props, the component does not blow up. This is also a
+potential state the component might be in during loading. Any interactive
+elements should be disabled.
+
+```jsx
+---
+title: Pagination in a loading state
+---
+<Pagination />
+```
+
+## totalRecordCount
+
+A number that specifies the length of the data.
+
+### Empty
+
+After loading data and passing props to our component, it is possible that data has a length of 0. In such cases, the component still have disabled input
+but the user will see additional indication that there are no records to display.
+
+```jsx
+---
+title: Pagination with dropdownIndex
+---
+<Pagination totalRecordCount={0} />
+```
+
+### With data but no state
+
+When we have a `totalRecordCount` greater than 1, Pagination values are displayed. Nothing is broken and it presents correctly.
+
+```jsx
+---
+title: With data but no state
+---
+<Pagination totalRecordCount={65} />
+```
+
+> Use the `usePaginationState` hook to provide this component with state.

packages/cascara/src/ui/Pagination/Pagination.js

@@ -8,14 +8,14 @@ import Boundaries from '../../system-components/Boundaries';
 import getStatusFromDataLength from '../../lib/getStatusFromDataLength';
 
 const propTypes = {
-  // The state of the Pagination component from the usePaginationState hook
+  /** The state of the Pagination component from the usePaginationState hook */
   state: pt.exact({
     currentPage: pt.number,
     perPage: pt.number,
     setCurrentPage: pt.func,
     setPerPage: pt.func,
   }),
-  // The total number of records. undefined (default) sets the component to loading state. 0 sets the component to an empty state.
+  /** The total number of records. undefined (default) sets the component to loading state. 0 sets the component to an empty state. */
   totalRecordCount: pt.number,
 };
 

packages/cascara/src/ui/Tabs/Tabs.doc.mdx.DISABLED

@@ -0,0 +1,49 @@
+---
+title: Tabs
+propTable: Tabs.js
+status: 'ALPHA'
+---
+
+# Public API
+
+WARNING! This is an alpha release so we can try to get this code in and working to kick the tires.
+
+## `tabs`
+
+An array of objects used to tell Tabs what to display.
+
+```jsx
+---
+title: Tabs with 3 panels
+---
+<Tabs
+  tabs={[
+    {
+      label: 'Panel A',
+      content: (
+        <>
+          <h3>I am a panel</h3>
+          <p>Hey there friend!</p>
+        </>
+      ),
+    },
+    {
+      label: 'Panel B',
+      content: <p>I am a new panel.</p>,
+    },
+    {
+      label: 'Panel C',
+      content: (
+        <>
+          <h3>A Third Panel</h3>
+          <p>
+            Lorem ipsum dolor, sit amet consectetur adipisicing elit. Molestias
+            voluptatum illum voluptatibus autem esse eaque totam hic placeat
+            dignissimos nisi.
+          </p>
+        </>
+      ),
+    }
+  ]}
+/>
+```

packages/cascara/src/ui/Tabs/Tabs.js

@@ -9,12 +9,16 @@ import TabPanel from './TabPanel';
 const TAB_FALLBACK = <div className='ui bottom attached loading tab segment' />;
 
 const propTypes = {
+  /** An array of objects used to tell Tabs what to display. */
   tabs: pt.arrayOf(
     pt.shape({
+      /** The content to display */
       content: pt.oneOfType([pt.arrayOf(pt.node), pt.node]),
+      /** The text to display in the Tab button */
       label: pt.string.isRequired,
     })
   ),
+  /** A title for the whole section */
   title: pt.string,
 };