Composing opinionated Stitches Components

[peduarte]

I'd like to open up a discussion about composing Stitches components which include pre-defined props/variants/styles.

A common example of this is to create higher-level components, which implement low-level components.

For the sake of this issue, I'll be using the following components:

• low-level component: Text - contains its base styles and variants
• high-level component: Title - implements Text with a set of opinions, eg: which variant to use.

The way to do this currently, is like so:

export const Text = styled('span', {
  fontFamily: "$system",
  variants: {
    size: {
      1: { fontSize: "$1" },
      2: { fontSize: "$2" },
      3: { fontSize: "$3" },
    }
  }
})

export const Title = props => (
  <Text 
    {...props}
    as="h1",
    size={{
      initial: "2",
      bp1: "3"
    }}
    css={{
      textTransform: "uppercase",
      lineHeight: "1.2em",
      ...props.css
      bp1: {
        lineHeight: "1.3em",
        ...props.css.bp1
      }
    }}
  />
)

Technically this would work, but it suffers from the following issues:

1. The Title component is no longer types, resulting in a poorer DX
2. In order to ensure that any css passed in is properly merged, we need to merge the CSS in each used breakpoint
3. A lot of boilerplate

---

To solve issue number 1, lack to typing, we need to do:

export const Text = styled('span', {...})

type TitleProps = React.ComponentProps<typeof Text>
export const Title = (props: TitleProps) => (...)

Related info on this in this discussion

---

To solve issue number 2, merging css objects, we could introduce a css.compose function:

<Text
  css={css.compose(
    {
      textTransform: 'uppercase',
      lineHeight: '1.2em',
      bp1: {
        lineHeight: '1.3em',
      },
    },
    props.css
  )}
/>;

---

To solve issue number 3, too much boilerplate, we introduce a first-class API to set default props, thinking of something along the lines of withProps. Similar to Reacts defaultProps (which is being deprecated). This solution would ensure the typings are correct and that any css passed in is properly merged:

export const Text = styled('span', {...})
export const Title = Text.withProps({
  as: "h1",
  size: {
    initial: "2",
    bp1: "3"
  },
  css: {
    textTransform: "uppercase",
    lineHeight: "1.2em",
    bp1: {
      lineHeight: "1.3em",
    }
  }
})

We currently have a suggestion for a withComponent API, but wonder if we can keep everything under one simple API.

---

Conclusion

The idea is that we keep our options open. If someone just needs to compose a low-level component and set a few opinions, such as which variant to use, they can use the withProps API.

If someone needs to compose a low-level component, but add extra functionality - such as a loading animation on a button - they can manually type their components with React.ComponentProps<typeof StitchesComponent>.

Finally, if someone needs to merge css objected passed in from the outside, they can use the css.compose function.

[jjenzz]

My only concern with the .withProps suggestion is that by adding these statics, it allows consumers to edit them after creation (this is an issue with our composeVariants API also):

// Text.tsx
export const Text = styled('span', {...})

// Link.tsx
import { Text } from './Text';
Text.withProps = { as: 'a' };
export const Link = Text;

// App.tsx
import { Text } from './Text';
import { Link } from './Link';
export const App = () => (
  <div>
    <Link href="#">Link</Link>
    <Text>This will be an anchor but only because `Link` is used in the same file!!</Text>
  </div>
)

You can see a demonstration of this issue with our composeVariants API here: https://codesandbox.io/s/boring-meadow-pn1p8

I really think both of these APIs need to happen before the component is created (much like attrs in styled-components):

const Title = styled.withProps({})(Text, {});

And for composeVariants, I mentioned something internally about doing something like this instead (but perhaps needs some more thought):

const Button = styled(
  {
    border: 0,
    variants: {
      color: {},
      appearance: {},
    }
  }, 

  // compoundVariants
  {
    composes: { color: 'red', appearance: 'outline' },
    color: 'gray',
    border: '1px solid gray',
  },
  {
    composes: { color: 'violet', appearance: 'outline' },
    color: 'violet',
    border: '1px solid violet',
  },
);

[peduarte]

My only concern with the .withProps suggestion is that by adding these statics, it allows consumers to edit them after creation

That's a good point 👍

const Title = styled.withProps({})(Text, {});

This looks very odd to me. I can't explain why but I'm not finding it very intuitive. I looks like if I define it before the creating, I wont have access to the variants since they've not been created yet.

And for composeVariants, I mentioned something internally about doing something like this instead (but perhaps needs some more thought):

I think there's something here. Im thinking either a third argument as you have it, or much like the special variants key, we can introduce a compoundVariants key too?

But anyway, we have some interesting discussion about compound variants here. So we can talk more about it there or create a new discussions dedicated for it.

[jjenzz]

This looks very odd to me. I can't explain why but I'm not finding it very intuitive. I looks like if I define it before the creating, I wont have access to the variants since they've not been created yet.

I hear you. I'm not fussed particularly about the API I'm just raising that whatever we choose probably should happen before creation. Having said that, we've all been using defaultProps for years without issue so perhaps okay. I do wonder if this is one of the reasons why it's being deprecated though.

An alternative is:

const Button = styled('button', {
  color: 'red',
})({ 
  as: 'h1',
});

// can be written as:
const button = styled('button', {});
button.compoundVariants({});
const Button = button({ as: 'h1' });

This would solve both API issues, but without default props or compounds they would still have to call it:

const Button = styled('button', {})();

[swudged]

Chiming in! I agree a lot that .withProps static could suffer from exposing too much. I like @jjenzz's approach of passing in the attrs and wonder if the API surface area can be reduced further by passing in attrs as part of the configuration in the same way that variants work? E.g:

export const Button = styled('button', {
    variants: {
        appearance: {
            primary: {
                color: '$primary'
            },
            highlight: {
                color: '$highlight',
            },
       }
    },
    attrs: {
        appearance: 'primary', // default
    },
});

export const HighlightedButton = styled(Button, {
    attrs: {
        appearance: 'highlight', // override
    },
});

// or:

<Button appearance="highlight" />

Downsides:

// y tho
<HighlightedButton appearance="primary" />`

If this approach were taken, should attrs as a key be used or would something like defaultAttrs be preferred to give clarity to authors of it's functionality?

[afzalsayed96]

What about something like this?

export const Text = styled('span', {
  fontFamily: "$system",
  variants: {
    size: {
      1: { fontSize: "$1" },
      2: { fontSize: "$2" },
      3: { fontSize: "$3" },
    }
  }
})

export const Title = styled(Text, {
  textTransform: "uppercase",
  lineHeight: "1.2em",
  bp1: {
    lineHeight: "1.3em"
  }
})

Title.defaultProps = {
  as: "h1",
  size: {
    initial: "2",
    bp1: "3"
  }
}

[aarongarciah]

@afzalsayed96 React is deprecating defaultProps so better not rely on that.

facebook/react#16210