Merge pull request #62 from octopusthink/add/list-component

Add List component

package.json

@@ -39,6 +39,7 @@
     "prop-types": "^15.7.2",
     "react": "^16.8.6",
     "react-dom": "^16.8.6",
+    "shortid": "^2.2.14",
     "shx": "^0.3.2"
   },
   "devDependencies": {

src/components/List/Heading.js

@@ -0,0 +1,7 @@
+import React from 'react';
+
+export const ListHeading = (props) => {
+  return <React.Fragment {...props} />;
+};
+
+export default ListHeading;

src/components/List/Item.js

@@ -0,0 +1,30 @@
+import { css } from '@emotion/core';
+import styled from '@emotion/styled';
+import PropTypes from 'prop-types';
+import React from 'react';
+
+export const ListItem = ({ children, ...otherProps }) => {
+  return <li {...otherProps}>{children}</li>;
+};
+
+ListItem.defaultProps = {
+  children: undefined,
+};
+
+ListItem.propTypes = {
+  /** @ignore */
+  children: PropTypes.node,
+};
+
+const StyledListItem = styled(ListItem)(({ theme }) => {
+  return css`
+    position: relative;
+    margin: 0 0 ${theme.spacing.padding.xs};
+    &::before {
+      position: absolute;
+      right: 101%;
+    }
+  `;
+});
+
+export default StyledListItem;

src/components/List/Paragraph.js

@@ -0,0 +1,7 @@
+import React from 'react';
+
+export const ListParagraph = (props) => {
+  return <React.Fragment {...props} />;
+};
+
+export default ListParagraph;

src/components/List/README.md

@@ -0,0 +1,101 @@
+A `<List>` is a collection of related elements of equal weight, presented in an itemised fashion.
+
+Use the `<List.Item>` component for each item in your list.
+
+```jsx
+<List numbered>
+  <List.Heading>Things to do</List.Heading>
+  <List.Item>Take shower. 🛀</List.Item>
+  <List.Item>Brush teeth. 😁</List.Item>
+  <List.Item>Take over world. 🌍</List.Item>
+</List>
+```
+
+## Usage
+
+Use a list to make blocks of text easier to read, and to break information into manageable chunks.
+
+
+Don't use a `<List>` for:
+
+- A collection of unrelated items. Use a `<Paragraph>` instead, or break the collection into smaller lists of related items.
+- Presenting long or complex pieces of data. Use a `<Paragraph>` or a `<DataTable>` instead.
+- A list of checkboxes, radio buttons, or other elements that require user interactivity. Use a `<Choice>` instead.
+- A list of key/value pairs, such as a list of definitions or descriptions. Use a `<DescriptionList>` instead.
+
+## Appearance
+
+- Choose a bullet and numbering style and use them consistently across your site or app. Don't mix styles unless you have a good reason for doing so.
+- Avoid lists of more than ten items. If you have a long list, consider breaking it up into smaller, more specific lists for more meaning and comprehension.
+- Lists should use body text styling so they look identical to other body copy, especially when used in editorial copy. If a list stands alone, it can use more distinct typography.
+- The space between each individual list item should be slightly bigger than the line-height inside the list item.
+- Lists can be nested, but avoid too much nesting. As a general rule, nest lists to a maximum of three levels. If you need more levels, consider other ways of breaking up your content, like using an individual list for each top-level list item.
+- Arrange list items in a logical way, even if they aren't sequential numbered steps. Bulleted lists can be arranged by priority, by order of importance, by size, alphabetically, numerically.
+
+## Variations
+
+Use a bulleted list when the order of items doesn't matter and to present content of equal status or value. Bulleted lists can be rearranged without losing any meaning.
+
+```jsx
+<List>
+  <List.Item>cats</List.Item>
+  <List.Item>dogs</List.Item>
+  <List.Item>mice</List.Item>
+</List>
+```
+
+<!--
+TODO: Implement an Icon list.
+Use an icon list when you want to provide additional semantic meaning—for instance, to show dos and don'ts.
+
+[example]
+-->
+
+Use numbered lists when the order of the items is relevant, or to imply sequence and order. They are commonly used when giving instructions or steps in a process.
+
+```jsx
+<List numbered>
+  <List.Paragraph>How to file taxes:</List.Paragraph>
+  <List.Item>Obtain wine.</List.Item>
+  <List.Item>Crack open wine.</List.Item>
+  <List.Item>Start drinking.</List.Item>
+  <List.Item>Spread papers in an organised fashion around room.</List.Item>
+  <List.Item>Reluctantly do taxes.</List.Item>
+</List>
+```
+
+## Voice & Tone
+
+- Introduce lists with a lead-in `<List.Paragraph>` ending in a colon (eg: "My favourite things:") or a `<List.Heading>` with no punctuation.
+- If list items use a single word only, start each item with a lowercase letter, and do not use a full stop at the end. (eg: "cat")
+- If list items use full sentences or sentence fragments (subject and verb), start each item with an uppercase letter and use a full stop at the end. (eg: "The cat ate a mouse.")
+- Never use commas or semicolons at the end of list items.
+- Use list items that are grammatically parallel to reflect their equal weight. For example, do not mix passive voice with active voice or declarative statements with imperative commands, and follow the same phrase structure for each item in the list.
+
+## Accessibility
+
+Using lists well will help improve the accessibility of your site.
+
+List items are conveyed as a group of related elements to assistive technology users. Assistive technologies may announce the total number of items in a list, give the relevant position of each item in a list, and provide shortcuts to quickly traverse a list.
+
+- If your list has a title or lead-in phrase, use a `<List.Heading>` or `<List.Paragraph>` component, inside the list as the first component. This will identify it as the list header using the `aria-labelledby` attribute.
+- Keep list labels as short as possible to communicate your intent.
+- Use a bulleted list for lists where the order isn't important, and a numbered list when it is.
+- Don't use a list for stylistic or presentation needs only.
+- Use semantic HTML elements (`<ol>`, `<ul>`, and `<li>`) to mark up lists. (Nautilus will handle this for you!)
+
+```jsx
+<List>
+  <List.Heading level={4}>Tasty fruit</List.Heading>
+  <List.Item>apples 🍏</List.Item>
+  <List.Item>kiwis 🥝</List.Item>
+  <List.Item>mangos 🥭</List.Item>
+</List>
+
+<List numbered>
+  <List.Paragraph>The best motorcycles, in order:</List.Paragraph>
+  <List.Item>Honda CBR 125R</List.Item>
+  <List.Item>Honda CB400 Four</List.Item>
+  <List.Item>Ducati 848</List.Item>
+</List>
+```

src/components/List/__snapshots__/index.test.js.snap

@@ -0,0 +1,118 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`List List.Heading should render a heading outside the list if one is provided 1`] = `
+.emotion-2 {
+  color: #3b3f45;
+  margin: 0 0 3.2rem;
+  font-family: -apple-system,BlinkMacSystemFont,San Francisco,Roboto,Segoe UI,Helvetica Neue,sans-serif;
+  font-weight: 400;
+  font-size: 1.8rem;
+  line-height: 1.5555555555555556;
+  padding: 0;
+}
+
+.emotion-2 > .eo6n83v0 {
+  list-style: none;
+}
+
+.emotion-2 > .eo6n83v0::before {
+  content: '\\2022';
+  font-size: 0.6em;
+  line-height: 2.8;
+}
+
+.emotion-0 {
+  margin: 0 0 3.2rem;
+  font-family: -apple-system,BlinkMacSystemFont,San Francisco,Roboto,Segoe UI,Helvetica Neue,sans-serif;
+  font-weight: 700;
+  font-size: 4.4rem;
+  line-height: 1;
+}
+
+.eijrly0 + .emotion-0,
+ul + .emotion-0,
+ol + .emotion-0,
+dl + .emotion-0 {
+  margin-top: 3.2rem;
+}
+
+<div>
+  <h3
+    class="emotion-0 emotion-1"
+    data-testid="description"
+    id="fruits"
+  >
+    Tasty fruits
+  </h3>
+  <ul
+    aria-labelledby="fruits"
+    class="emotion-2 emotion-3"
+  />
+</div>
+`;
+
+exports[`List List.Paragraph should render a paragraph outside the list if one is provided 1`] = `
+.emotion-6 {
+  color: #3b3f45;
+  margin: 0 0 3.2rem;
+  font-family: -apple-system,BlinkMacSystemFont,San Francisco,Roboto,Segoe UI,Helvetica Neue,sans-serif;
+  font-weight: 400;
+  font-size: 1.8rem;
+  line-height: 1.5555555555555556;
+  padding: 0;
+}
+
+.emotion-6 > .emotion-3 {
+  list-style: none;
+}
+
+.emotion-6 > .emotion-3::before {
+  content: '\\2022';
+  font-size: 0.6em;
+  line-height: 2.8;
+}
+
+.emotion-2 {
+  position: relative;
+  margin: 0 0 0.4rem;
+}
+
+.emotion-2::before {
+  position: absolute;
+  right: 101%;
+}
+
+.emotion-0 {
+  color: #3b3f45;
+  margin: 0 0 3.2rem;
+  font-family: -apple-system,BlinkMacSystemFont,San Francisco,Roboto,Segoe UI,Helvetica Neue,sans-serif;
+  font-weight: 400;
+  font-size: 1.8rem;
+  line-height: 1.5555555555555556;
+}
+
+<div>
+  <p
+    class="emotion-0 emotion-1"
+    data-testid="description"
+    id="cars"
+  >
+    Here are some cars:
+  </p>
+  <ul
+    aria-labelledby="cars"
+    class="emotion-6 emotion-7"
+  >
+    <li
+      class="emotion-2 emotion-3"
+    >
+      Honda Civic
+    </li>
+    <li
+      class="emotion-2 emotion-3"
+    >
+      Ford Prefect
+    </li>
+  </ul>
+</div>
+`;