Merge pull request #1520 from creative-commoners/pulls/2/storybook-docs

ENH Storybook documentation

.storybook/main.js

@@ -29,7 +29,8 @@ const config = {
     storyStoreV7: false
   },
   docs: {
-    autodocs: "tag"
+    autodocs: "tag",
+    defaultName: 'Documentation',
   },
   webpackFinal: async (config) => {
     return {

client/src/components/ActionMenu/tests/ActionMenu-story.js

@@ -3,13 +3,29 @@ import ActionMenu from 'components/ActionMenu/ActionMenu';
 import { DropdownItem } from 'reactstrap';
 
 export default {
-    title: 'Admin/ActionMenu',
+  title: 'Admin/ActionMenu',
+  component: ActionMenu,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'ActionMenu Component description.'
+      },
+      canvas: {
+        sourceState: 'shown',
+      },
+      controls: {
+        sort: 'alpha',
+      }
+    }
+  },
+  argTypes: {}
 };
 
 export const Single = () => (
-    <ActionMenu>
-        <DropdownItem>Item One</DropdownItem>
-        <DropdownItem>Item Two</DropdownItem>
-        <DropdownItem>Item Three</DropdownItem>
-    </ActionMenu>
+  <ActionMenu>
+    <DropdownItem>Item One</DropdownItem>
+    <DropdownItem>Item Two</DropdownItem>
+    <DropdownItem>Item Three</DropdownItem>
+  </ActionMenu>
 );

client/src/components/Badge/tests/Badge-story.js

@@ -3,35 +3,65 @@ import { jsxDecorator } from 'storybook-addon-jsx';
 import Badge, { statuses } from 'components/Badge/Badge';
 
 export default {
-    title: 'Admin/Badges',
-    component: Badge,
-    decorators: [
-        jsxDecorator,
-        (Story) => <div><Story/></div>
-    ],
-    argTypes: {
-        status: {
-          control: 'select',
-          options: statuses
-        },
-        inverted: {
-          control: 'boolean'
-        },
-        className: {
-          control: 'inline-radio',
-          options: {
-            'Empty class name': '',
-            'badge-pill class name': 'badge-pill'
-          }
-        }
+  title: 'Admin/Badges/Badge',
+  component: Badge,
+  decorators: [
+    jsxDecorator
+  ],
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Badge component for displaying a message in a Bootstrap "badge" style.'
+      },
+      canvas: {
+        sourceState: 'shown',
+      },
+    }
+  },
+  argTypes: {
+    message: {
+      description: 'The string to display in the badge.',
+      control: 'text',
+    },
+    status: {
+      description: "The status for the badge, takes bootstrap's values.",
+      control: 'select',
+      options: statuses,
+      table: {
+        type: { summary: 'success, warning, danger, info, default' },
+        defaultValue: { summary: 'default' },
       }
-  };
+    },
+    inverted: {
+      description: 'If the colours should be inverted.',
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    className: {
+      description: 'Any extra classes to apply for the badge.',
+      control: 'inline-radio',
+      options: {
+        'Empty class name': '',
+        'badge-pill class name': 'badge-pill'
+      },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'badge-pill' },
+      },
+    }
+  }
+};
 
+/** Test message */
 export const _Badge = {
-    args: {
-        message: 'Hello World!',
-        status: 'default',
-        className: 'badge-pill',
-        inverted: false
-    }
+  args: {
+    message: 'Hello World!',
+    status: 'default',
+    className: 'badge-pill',
+    inverted: false
+  }
 };

client/src/components/Breadcrumb/tests/Breadcrumb-story.js

@@ -7,27 +7,27 @@ import { Component as Breadcrumb } from 'components/Breadcrumb/Breadcrumb';
 
 // Simple values to displays in the select fields.
 const icons = [
-    '',
-    'font-icon-edit-list',
-    'font-icon-calendar',
-    'font-icon-p-home',
-    'font-icon-cart',
+  '',
+  'font-icon-edit-list',
+  'font-icon-calendar',
+  'font-icon-p-home',
+  'font-icon-cart',
 ];
 const levels = [
-    'First',
-    'Second',
-    'Third',
-    'Fourth',
-    'Fifth',
-    'Sixth',
-    'Seventh',
-    'Eighth',
+  'First',
+  'Second',
+  'Third',
+  'Fourth',
+  'Fifth',
+  'Sixth',
+  'Seventh',
+  'Eighth',
 ];
 
 // Build an action to handle the click on the crumbs
 const crumbAction = (event) => {
-    event.preventDefault();
-    return action('onClick')(event);
+  event.preventDefault();
+  return action('onClick')(event);
 };
 crumbAction.toString = () => 'onClick';
 
@@ -39,49 +39,92 @@ crumbAction.toString = () => 'onClick';
  * @returns {Object[]}
  */
 const buildBreadCrumb = (position, rank, icon) => {
-    const level = levels[position];
-    let crumb = [
-        {
-            text: `${level} level`,
-            href: '#',
-            onClick: crumbAction,
-        },
-    ];
+  const level = levels[position];
+  let crumb = [
+    {
+      text: `${level} level`,
+      href: '#',
+      onClick: crumbAction,
+    },
+  ];
 
-    if (level === rank) {
-        crumb[0].icon = { className: icon };
-    } else {
-        crumb = crumb.concat(buildBreadCrumb(position + 1, rank, icon));
-    }
+  if (level === rank) {
+    crumb[0].icon = { className: icon };
+  } else {
+    crumb = crumb.concat(buildBreadCrumb(position + 1, rank, icon));
+  }
 
-    return crumb;
+  return crumb;
 };
 
 export default {
-    title: 'Admin/Breadcrumb',
-    component: Breadcrumb,
-    decorators: [
-        jsxDecorator
-    ],
-    argTypes: {
-      levels: {
-        control: 'select',
-        options: levels
+  title: 'Admin/Breadcrumb',
+  component: Breadcrumb,
+  decorators: [
+    jsxDecorator
+  ],
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'The breadcrumbs for the current section of the CMS.'
       },
-      icons: {
-        control: 'select',
-        options: icons
+      canvas: {
+        sourceState: 'shown',
       },
-    },
-    args: {
-        levels: 'First',
-        icons: ''
+      controls: {
+        sort: 'alpha',
+      }
     }
+  },
+  argTypes: {
+    href: {
+      table: {
+        type: { summary: 'string' },
+      }
+    },
+    text: {
+      table: {
+        type: { summary: 'string' },
+      }
+    },
+    crumbs: {
+      description: 'An array of objects, each object should have a `text` and `href` key.',
+      table: {
+        type: { summary: 'array' },
+      }
+    },
+    level: {
+      control: 'select',
+      options: levels,
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    icon: {
+      description: 'The font icon font name.',
+      control: 'select',
+      options: icons,
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    icons: {
+      description: 'Array of icons',
+      table: {
+        type: { summary: 'array' },
+      },
+    },
+  },
+  args: {
+    level: 'First',
+    icon: ''
+  }
 };
 
 export const _Breadcrumb = (args) => {
-    // eslint-disable-next-line no-shadow
-    const { levels, icons } = args;
-    return (<Breadcrumb crumbs={buildBreadCrumb(0, levels, icons)}/>);
+  // eslint-disable-next-line no-shadow
+  const { level, icon } = args;
+  return (<Breadcrumb crumbs={buildBreadCrumb(0, level, icon)}/>);
 };
 

client/src/components/Button/tests/BackButton-story.js

@@ -0,0 +1,80 @@
+import React from 'react';
+import { jsxDecorator } from 'storybook-addon-jsx';
+import { action } from '@storybook/addon-actions';
+import BackButton from '../BackButton';
+
+const colors = [
+  'primary',
+  'secondary',
+  'success',
+  'info',
+  'warning',
+  'danger',
+  'link',
+];
+const sizes = ['sm', 'md', 'lg'];
+const icons = [
+  '',
+  'search',
+  'sync',
+  'plus-circled',
+  'cancel-circled',
+  'check-mark',
+  'edit',
+];
+
+const onClick = (event) => {
+  event.preventDefault();
+  return action('onClick')(event);
+};
+onClick.toString = () => 'onClick';
+
+export default {
+  title: 'Admin/Buttons/BackButton',
+  component: BackButton,
+  decorators: [
+    jsxDecorator
+  ],
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Generic Button component to allow users to return to a preview view. It displays a `<` icon and has an appropriate `aria-label.'
+      },
+      canvas: {
+        sourceState: 'shown',
+      },
+      controls: {
+        sort: 'alpha',
+      }
+    }
+  },
+  argTypes: {
+    children: {
+      description: "If present, any nested content inside the button will apply to the `aria-label` attribute. Otherwise, the localised string 'Back' will be used.",
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    className: {
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+      }
+    },
+    onClick: {
+      action: 'clicked',
+      table: {
+        type: { summary: 'function' },
+      }
+    }
+  }
+};
+
+export const _BackButton = (args) => <BackButton {...args}/>;
+_BackButton.args = {
+  onClick,
+  className: '',
+  children: 'Back'
+};