tachyons-measured v1.0.3

📏 📐 tachyons-measured

A set of higher order components (HOC) for creating stateless functional UI components using tachyons.

• API
  • Media Query Support
  • Higher Order Components
  • Compose
  • Performance
• Example
• Why?
• Inspired by and Related to

API

Media Query (MQ) Support

The following properties support the media query syntax:

• r, rounded, bw
• f, lh
• h, w
• pa, pl, pr, pb, pt, pv, ph
• ma, ml, mr, mb, mt, mv, mh
• na, nl, nr, nb, nt

This means that you can either provide regular values – such as a scale step number and literal values – or an object which specifies values by breakpoints.

For example: <Text f={1} /> or <Text f={{ all: 3, ns: 2, m: 1, l: 'headline' }} />

all: All breakpoints (unless otherwise specified with another breakpoint) ns: Not small m: Medium l: Large

Higher Order Components

• withBaseStyles
• withSpacing
• withBackgroundColor
• withColor
• withSize
• withTypography
• withBorder
• withDefaults
• withMeasured

withBaseStyles

withBaseStyles(
  baseStyles: Array<string> or string
): HigherOrderComponent

HOC for creating a styled component with a set of classNames applied to it.

const ButtonLink = compose('f6 link dim br1 ph3 pv2 mb2 dib white bg-black')('a');

<ButtonLink>Link Text</ButtonLink>

withSpacing

withSpacing(): HigherOrderComponent

Exposes the spacing scale as props.

const Div = withSpacing('div');

<Div
  mh={3} mv={{ l: 4, m: 3, ns: 2, all: 1 }}
  nl={{ l: 3, m: 2, ns: 4, all: 1 }}
  pr={4} pl={4} pv={2}
  className="myClass my-other-class"
/>

withBackgroundColor

withBackgroundColor(
  colors: Array<string>
): HigherOrderComponent

Allows you to set the background color using the bg prop. You will have to provide it a list of colour names that you are using in your project.

const clrs = ['red', 'green', 'blue', 'washed-yellow'];
const Div = withBackgroundColor(clrs)('div');

<Div
  bg="washed-yellow"
  className="myClass my-other-class"
/>

withColor

withColor(
  colors: Array<string>
): HigherOrderComponent

Allows you to set the font color using the color prop. You will have to provide it a list of colour names that you are using in your project.

const clrs = ['medium-gray', 'red', 'green', 'blue'];
const Text = withColor(clrs)('p');

<Text
  color="medium-gray"
  className="myClass my-other-class"
/>

withSize

withSize(): HigherOrderComponent

Exposes widths & heights as props.

const Div = withSize('div');;

<Div
  w={{ l: 5, m: 4, ns: 'third', all: 3 }}
  h={5}
  className="myClass my-other-class"
/>

withTypography

withTypography(): HigherOrderComponent

Allows you to set the font size and line-height using the f and lh props respectively.

const Text = withTypography('p');;

<Text
  f={{ l: 4, m: 3, ns: 2, all: 1 }}
  lh="copy"
  className="myClass my-other-class"
/>

withBorder

withBorder(
  colors: Array<string>
): HigherOrderComponent

Allows you to set border styles using props. You will have to provide it a list of colour names that you are using in your project.

const clrs = ['medium-gray', 'red', 'green', 'blue'];
const Div = withBorder(clrs)('div');

<Div
  ba="gray" bw={2}
  radius={{ l: 1, m: 2, ns: 100, all: 4 }}
  rounded={{ l: 'bottom', m: 'top', ns: 'right', all: 'left' }}
  className="myClass my-other-class"
/>

withDefaults

withDefaults(
  defaultsForProps: Object
): HigherOrderComponent

Allows you to provide default values for any props.

const Title = compose(
  withTypography,
  withDefaults({ f: 1, lh: 'title' }),
)('h1');

// Will receive f as 1 and lh as 'title'
<Title className="myClass my-other-class" />
// Will receive f as 2 and lh as 'title'
<Title f={2} className="myClass my-other-class" />

withMeasured

withMeasured(
  colors: Array<string>
): HigherOrderComponent

A composition of withSpacing, withBackgroundColor(colors), withColor(colors), withSize, withBorder(colors) and withTypography.

const clrs = ['white', 'red', 'green', 'blue'];
export const Block = withMeasured(clrs)('div');

<Block
  f={{ l: 4, m: 3, ns: 2, all: 1 }}
  lh="copy"
  mh={3} mv={2} mt={4} nl={3}
  pa={{ l: 4, m: 4, ns: 3, all: 2 }}
  bg="blue"
  color="white"
  w={5}
  h={{ l: 50, m: 4, ns: 3, all: 2 }}
  bb="gray" bw={{ l: 1, m: 2, ns: 3, all: 4 }}
  radius="pill"
  rounded="top"
/>

Compose

tachyons-measured provides the ramda compose function. However, should be able to use any compose function. Such as the one provided by underscore or recompose, etc.

import { compose } from 'tachyons-measured';

Performance

All the HOC provided by this library are stateless and mostly just responsible for mapping or generating props. Therefore, they have been setup to be eagerly evaluated. This is based on the createEagerElement pattern from recompose.

Without eager evaluation the component tree would look something like this:

<withSpacing>
  <withBackgroundColor>
    <withColor>
      <withSize>
        <withBorder>
          <div>
            Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
          <div>
        <withBorder>
      <withSize>
    <withColor>
  <withBackgroundColor>
</withSpacing>

With eager evaluation all the HOC are collapsed into one component instance. This helps achieve better performance since a fewer component instances are created. Also, it should help with debugging since the component tree is much flatter.

<withSpacing(withBackgroundColor(withColor(withSize(withBorder(div)))))>
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</withSpacing(withBackgroundColor(withColor(withSize(withBorder(div)))))>

For more info see this talk by Andrew Clark

Example

We are going to replicate this Product Card. We start by creating some base components by enhancing HTML elements using tachyons-measured HOCs.

export const Block = withMeasured(clrs)('div');
export const Article = withMeasured(clrs)('article');
export const Heading = withMeasured(clrs)('h1');

export const Text = compose(
  withDefaults({ f: 5, lh: 'copy' }),
  withMeasured(clrs),
)('p');

export const Media = compose(
  withBorder(clrs),
  withSize,
  withSpacing,
  withBaseStyles('db'),
)('img');

The <ProductCard> component is simply the <Article> component with some default styles applied to it. Therefore, we can create the <ProductCard> by wrapping <Article> with the withDefaults HOC.

export const ProductCard = withDefaults({
  ba: 'black-10',
  radius: 2,
  bg: 'white',
  color: 'dark-gray',
})(Article);

Finally, we combine them all together to create the <CatProductCard>.

export const CatProductCard = props => (
  <ProductCard {...props}>

    <Media
      src="http://placekitten.com/g/600/300"
      w={100}
      radius={2} rounded="top"
      alt="kitten looking menacing."
    />

    <Block pa={2} ph={{ ns: 3 }} pb={{ ns: 3 }}>

      <Block w={100} mt={1} className="flex items-center">
        <Heading
          f={{ all: 5, ns: 4 }} mv={0}
          className="flex-auto"
        >
          Cat
        </Heading>
        <Heading f={5} mv={0}>$1,000</Heading>
      </Block>

      <Text
        mt={2}
        f={6} lh="copy" color="mid-gray"
        className="measure"
      >
        If it fits, i sits burrow under covers. Destroy couch leave hair
        everywhere, and touch water with paw then recoil in horror.
      </Text>

    </Block>
  </ProductCard>
);

We are passing all props from <CatProductCard> to <ProductCard>. This means when we are using <CatProductCard> we can use props to control the styles for a specific instance. For example:

<CatProductCard
  w={{ all: 100, m: 5, l: 5 }}
  className="center"
/>

🚨 For more examples see the examples directory.

Why?

1. It allows you to quickly create styled and/or stateless functional UI components which use tachyons for styling.

2. It helps break up the styles into multiple props. This avoids className from becoming long and hard to read.

   <Button
     f={4} lh="solid"
     bg="near-white" color="black-60"
     br="3" rounded="top"
     mv={0} pv={2} ph={3}
   />

3. It enforces typechecking using propTypes. This helps catch values not supported by tachyons.

4. It makes it easier to provide defaults (see the explanation below).

When building components we often want to provide some base styling and then allow the user to override some of that styling. This can be challenging to achieve by providing all the overriding-styles through one prop. For example:

const Button = ({ className, ...props}) => {
  const styles = classNames('f6', 'link', 'dim', 'br1', 'bn',
    'ph3', 'pv2', 'mb2', 'dib', 'bg-green', 'white', className);

  return (
    <a className={styles} {...props} />
  );
};

This component provides all the base-styles. Including the default background and text colours. There are many ways to do this however, for this particular example I'm using classNames.

// Will render with green background and white text
<Button className="mr3">Button Text</Button>
// Will render with blue background and white text
<Button className="bg-blue mr3">Button Text</Button>
// Will render with green background and white text
<Button className="bg-red">Button Text</Button>

You might notice a problem with the above scenario. The first two buttons will render as expected however, the third one will not. This is because in tachyons CSS .bg-green is defined after .bg-red so it will take precedence.

/* Background colors */
.bg-red { background-color: #ff4136; }
  ...
.bg-green { background-color: #19a974; }
  ...
.bg-blue { background-color: #357edd; }

In order to get around this we can expose background and color as props.

const Button = ({
  bgColor = 'bg-green',
  color = 'white',
  className,
  ...props
}) => {
  const styles = classNames('f6', 'link', 'dim', 'br1', 'bn',
    'ph3', 'pv2', 'mb2', 'dib', bgColor, color, className);

  return (
    <a className={styles} {...props} />
  );
};

full example: codepen.io/winkerVSbecks/pen/LWBLYb

Inspired by and Related to

• tachyons-react
• tachyons
• github.com/jxnblk/rebass
• github.com/acdlite/recompose

Feedback

This is still in the early stages. Any feedback and bug reports are much appreciated. Please submit them here or reach out to me on twitter.