Merge pull request #1298 from flo-sch/feature/paragraph

feat: paragraph component

packages/components/index.d.ts

@@ -85,6 +85,17 @@ export type TextProps = BoxProps
  */
 export const Text: ForwardRef<HTMLDivElement, BoxProps>
 
+export interface ParagraphProps
+  extends Assign<React.ComponentPropsWithRef<'p'>, BoxOwnProps> {}
+/**
+ * Primitive typographic component.
+ *
+ * Text style variants can be defined in the theme.text object.
+ * The Paragraph component uses theme.text.default as its default variant style.
+ * @see https://theme-ui.com/components/paragraph
+ */
+export const Paragraph: ForwardRef<HTMLParagraphElement, ParagraphProps>
+
 export interface HeadingProps
   extends Assign<React.ComponentPropsWithRef<'h2'>, BoxOwnProps> {}
 /**

packages/components/src/Paragraph.js

@@ -0,0 +1,26 @@
+import React from 'react'
+import Box from './Box'
+
+export const Paragraph = React.forwardRef(({ sx, ...props }, ref) => (
+  <Box
+    ref={ref}
+    as="p"
+    variant="paragraph"
+    {...props}
+    sx={{
+      // reset margin by default: avoid relying on user-agent margins (not aware of theme-ui space scale)
+      margin: 0,
+      // set a max-width: avoid full-page paragraphs
+      '@media screen and (min-width: 36em)': {
+        maxWidth: '48rem',
+      },
+      ...sx,
+    }}
+    __themeKey="text"
+    __css={{
+      fontFamily: 'body',
+      fontWeight: 'body',
+      lineHeight: 'body',
+    }}
+  />
+))

packages/components/src/index.js

@@ -3,6 +3,7 @@ export { Flex } from './Flex'
 export { Grid } from './Grid'
 export { Button } from './Button'
 export { Link } from './Link'
+export { Paragraph } from './Paragraph'
 export { Text } from './Text'
 export { Heading } from './Heading'
 export { Image } from './Image'

packages/components/test/__snapshots__/index.js.snap

@@ -1043,6 +1043,28 @@ exports[`NavLink renders 1`] = `
 />
 `;
 
+exports[`Paragraph renders 1`] = `
+.emotion-0 {
+  box-sizing: border-box;
+  margin: 0;
+  min-width: 0;
+  font-family: body;
+  font-weight: body;
+  line-height: body;
+  margin: 0;
+}
+
+@media screen and (min-width: 36em) {
+  .emotion-0 {
+    max-width: 48rem;
+  }
+}
+
+<p
+  className="emotion-0"
+/>
+`;
+
 exports[`Progress renders 1`] = `
 .emotion-0 {
   box-sizing: border-box;

packages/components/test/index.js

@@ -11,6 +11,7 @@ import {
   Heading,
   Image,
   Link,
+  Paragraph,
   Text,
   Label,
   Input,
@@ -64,6 +65,12 @@ const theme = {
     default: {
       fontSize: 3,
     },
+    block: {
+      variant: 'default',
+      textAlign: 'justify',
+      textAlignLast: 'start',
+      textJustify: 'auto',
+    },
     heading: {
       fontSize: 5,
     },
@@ -288,6 +295,44 @@ describe('Link', () => {
   })
 })
 
+describe('Paragraph', () => {
+  test('renders', () => {
+    const json = renderJSON(
+      <ThemeProvider theme={theme}>
+        <Paragraph />
+      </ThemeProvider>
+    )
+    expect(json).toMatchSnapshot()
+  })
+
+  test('renders with variant prop', () => {
+    const variant = 'block'
+    const json = renderJSON(
+      <ThemeProvider theme={theme}>
+        <Paragraph variant={variant}>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        </Paragraph>
+      </ThemeProvider>
+    )
+    const style = theme.text[variant]
+    expect(json).toHaveStyleRule('text-align', style.textAlign)
+    expect(json).toHaveStyleRule('text-align-last', style.textAlignLast)
+    expect(json).toHaveStyleRule('text-justify', style.textJustify)
+  })
+
+  test('renders with sx prop', () => {
+    const margin = '8px'
+    const json = renderJSON(
+      <Paragraph
+        sx={{
+          margin,
+        }}
+      />
+    )
+    expect(json).toHaveStyleRule('margin', margin)
+  })
+})
+
 describe('Text', () => {
   test('renders', () => {
     const json = renderJSON(

packages/docs/src/gatsby-plugin-theme-ui/index.js

@@ -71,6 +71,13 @@ export default {
       fontWeight: 'heading',
       lineHeight: 'heading',
     },
+    block: {
+      variant: 'default',
+      my: 2,
+      textAlign: 'justify',
+      textAlignLast: 'last',
+      textJustify: 'auto',
+    },
     display: {
       variant: 'text.heading',
       fontSize: [5, 6],
@@ -195,23 +202,23 @@ export default {
       borderColor: 'gray',
       '&:focus': {
         borderColor: 'primary',
-        boxShadow: t => `0 0 0 2px ${t.colors.primary}`,
+        boxShadow: (t) => `0 0 0 2px ${t.colors.primary}`,
         outline: 'none',
       },
     },
     select: {
       borderColor: 'gray',
       '&:focus': {
         borderColor: 'primary',
-        boxShadow: t => `0 0 0 2px ${t.colors.primary}`,
+        boxShadow: (t) => `0 0 0 2px ${t.colors.primary}`,
         outline: 'none',
       },
     },
     textarea: {
       borderColor: 'gray',
       '&:focus': {
         borderColor: 'primary',
-        boxShadow: t => `0 0 0 2px ${t.colors.primary}`,
+        boxShadow: (t) => `0 0 0 2px ${t.colors.primary}`,
         outline: 'none',
       },
     },

packages/docs/src/pages/components/paragraph.mdx

@@ -0,0 +1,52 @@
+---
+title: Paragraph
+---
+
+# Paragraph
+
+Primitive typographic component meant to display text blocks, defaults to `<p>`.
+
+```js
+import { Paragraph } from 'theme-ui'
+```
+
+```jsx live=true
+<Paragraph>Hello World!</Paragraph>
+<Paragraph variant="block">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec nunc elit,
+  feugiat ut velit eget, pellentesque accumsan libero. Duis interdum ante sed
+  ipsum imperdiet congue nec non mauris. Quisque ac ultricies nunc. Sed nisi
+  diam, suscipit eu laoreet a, bibendum nec mauris. Aliquam tristique rhoncus
+  ipsum scelerisque egestas. Maecenas rhoncus malesuada mauris, vel porta ex
+  tincidunt non. Duis ac sapien in felis fermentum tristique. Nam a erat
+  faucibus, varius magna ac, interdum tortor. Aenean quis varius mi, nec
+  molestie neque. In dignissim diam in velit pharetra cursus. Integer gravida,
+  arcu non sagittis iaculis, justo leo facilisis augue, consequat mollis risus
+  erat quis velit. In turpis nibh, ornare ut facilisis id, dignissim non enim.
+  Fusce maximus elit sit amet dolor aliquet, et tristique elit eleifend. Aenean
+  ornare tortor sem, at sollicitudin ipsum scelerisque a.
+</Paragraph>
+<Paragraph as="small" sx={{ fontStyle: 'italic' }}>Something a bit less important</Paragraph>
+```
+
+Use the `as` prop to set the correct HTML element independent from styling.
+
+## Variants
+
+Text style variants can be defined in the `theme.text` object.
+The Paragraph component uses `theme.text.paragraph` as its default variant style.
+
+```js
+// example theme variants
+{
+  text: {
+    block: {
+      variant: 'paragraph',
+      my: 2,
+      textAlign: 'justify',
+      textAlignLast: 'start',
+      textJustify: 'auto',
+    },
+  }
+}
+```

packages/docs/src/sidebar.mdx

@@ -21,6 +21,7 @@
   - [Text](/components/text)
   - [Heading](/components/heading)
   - [Link](/components/link)
+  - [Paragraph](/components/paragraph)
   - [Image](/components/image)
   - [Card](/components/card)
   - [Forms](/components/forms)