feat(utils): add wrapper for the createComponent function

[mnajdova]

Introducing createComponent functionality as part of the public API in Stardust

This PR aims to fix #498 by adding a wrapper around the internal createComponent function. The API for the function looks like this:

export interface RenderStardustResultConfig {
  classes: ComponentSlotClasses
  rtl: boolean
}

export interface CreateStardustComponentConfig<P> {
  displayName: string
  render: (props: P & { stardust: RenderStardustResultConfig }) => React.ReactNode
}

const createComponent = <P extends {} = {}, S extends {} = {}>({
  displayName = 'StardustComponent',
  render,
}: CreateStardustComponentConfig<P>) => React.SFC<P> 

Only the bits related to the styles are added in the config of the component.

Usage example

Definition of the custom component

The createComponent function should be used for defining custom components in the following way:

export interface StyledButtonProps {
  styles?: ComponentSlotStyle
  variables?: ComponentVariablesInput
  children?: React.ReactNodeArray | React.ReactNode
}

const StyledButton: React.SFC<StyledButtonProps> = createComponent<StyledButtonProps, {}>({
  displayName: 'MyStyledButton',
  render({stardust, ...props}) {
    const { classes } = stardust
    
    return (<button className={cx(props.className, classes.root)} {...props} />)
  },
})

Example usage of the custom component

Some example usages of the StyledButton component would be:

Using styles and accessing the theme from the Provider

<StyledButton styles={({ theme: {siteVariables} }) => ({ backgroundColor: siteVariables.brand })}>
  My styled button
</StyledButton>

Using styles and accessing the props as they would use with some Stardust component

<StyledButton isRed styles={({props}) => ({backgroundColor: props.isRed ? 'red' : 'blue'})}>
  My red styled
</StyledButton>

Theming support

<Provider theme={{
  componentStyles: {
    StyledButton: {
      root: ({ props, variables, theme: {siteVariables} }) => ({
        backgroundColor: props.isRed ? (variables as any).red : siteVariables.brand,
      }),
    },
  },
  componentVariables: {
    StyledButton: {
      red: '#fc798c',
    },
  },
}}>
  <StyledButton isRed>My styled button on Provider</StyledButton>
</Provider>

[kuzhelov]

@mnajdova, please, note that example's code provided in description could be simplified:

const StyledButton = createComponent({
  displayName: 'MyStyledButton',
  render(stardust, props) {
    const { classes } = stardust
    
    // note that we should respect client's classes passed as well
    return (<button className={cx(props.className, classes.root)} {...props} />)
  },
})

[codecov]

Codecov Report

Merging #503 into master will increase coverage by 0.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #503      +/-   ##
==========================================
+ Coverage   88.41%   88.42%   +0.01%     
==========================================
  Files          42       42              
  Lines        1450     1452       +2     
  Branches      186      186              
==========================================
+ Hits         1282     1284       +2     
  Misses        163      163              
  Partials        5        5

Impacted Files	Coverage Δ
src/index.ts	100% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4fb1fc2...0739bfb. Read the comment docs.

[bmdalex]

left comments

[levithomason]

Minor changes requested, no blockers from me

[levithomason]

Next up we'll publish some docs and examples showing how to use this. There should be a new Guide for "Custom Components".

[brianespinosa]

Sweet!