We're phasing out Box, Flex and Grid in favor of our new styling API.

[mannycarrera4]

In Canvas Kit v10, we're introduced a new way of styling. This allows us to generate styles in a more efficient and predictable way rather than relying on Emotion's costly runtime. This also meant that we've decided as team to move away from style props and phase out our atomic level components.

Prior to v10, we heavily used our atomic level components such as Box, Flex and Grid which allowed us to use style props. The benefits where to give our consumers and ourselves a quick way to style an element.

However, the biggest fallback was the lack of understanding how styles merged especially when consumers would extend a component that used styled props and styled an element using the css prop or styled components from Emotion.

Why is style merging unpredictable with style props?

Style props create an unpredictable interface. A style prop is always valid according to TypeScript and JavaScript runtime, but whether that style prop actually applies the style depends on the implementation of the component you use.

If the component you use supports and only uses style props, the style prop works. If the component uses any other method of styling, like creating styled components, it will not work.

Example:


// before
// Component1.tsx
const Component1 = props => <Box padding={10} {...props} />
// MyComponent.tsx
<Component1 padding={20}>Hi!</Component1>
// padding is 20px
// after an edit to Component1
// Component1.tsx
const StyledBox = styled(Box)({
  padding: 10
})
const Component1 = props => <StyledBox {...props} />
// MyComponent.tsx
<Component1 padding={20}>Hi</Component1>
// padding is now 10px even though MyComponent.tsx didn't change and the developer thinks it should be 20px

Style props employ "prop drilling" to get the style prop all the way down to the Box element while styled and the css prop apply styles at every render. styled and css are predictable. They apply at the level you declare them. Style props drill down to the component that implements them.



Example:



const Component1 = props => <div css={{padding: 10}} {...props} />
const Component2 = props => <Component1 css={{padding: 20}} {...props} />

<Component2 css={{padding: 30}}>Hi!</Component2>

// Padding is always 30 as you expect because overrides happen at each layer

With mergeStyles, the cs prop works the same way - at each mergeStyles call. mergeStyles reduces every cs prop to className and style attributes the same way styled and the css prop reduce to a className. This is why you don't ever see a css prop being passed on the prop list. It is always removed and turned into a className

In order for us to move forward and to provide a more predictable way of style merging, we've decided as a team to start phasing out the usage of Box, Flex and Grid within Canvas Kit.

We hold the firm belief that we should not impose on our consumers a strict way of styling or how to overwrite styles, but we aim to guide you in the best approach to do so.

So what does styling look like if we don't use Box, Flex and Grid.

// Using Box which accepts style Props but style merging is unpredictable
interface MyComponentProp extends BoxProps {}

const MyComponent = createComponent('div')({
  displayName: 'MyComponent',
  Component: ({children, ...elemProps}: FlexProps, ref, Element) => {
    return (
      <Box padding="10px" backgroundColor="orange" as={Element} ref={ref} {...mergeStyles(elemProps, [myComponentStyles])}>
        {children}
      </Box>
    );
  },
});

interface MyComponentProp extends CSProps {}

const myComponentBaseStyles = createStyles({
  padding: '10px',
  backgroundColor: 'orange',
});

// No need for an atomic level components, accepts cs Prop and custom styles and style merging is predictable
const MyComponent = createComponent('div')({
  displayName: 'MyComponent',
  Component: ({children, ...elemProps}: MyComponentProp, ref, Element) => {
    return (
      <Element ref={ref} {...mergeStyles(elemProps, [myComponentBaseStyles])}>
        {children}
      </Element>
    );
  },
});

What about creating complex styles based on props or state?

We want to introduce a simpler way to group your styles, which would look like stencils. Here's a great discussion by @NicholasBoll describing how stencils would work. This allows consumers and us to style more complex components.

Ideally we'd also like to update createComponent so that it simplifies the types and usage of stencils.

interface MyComponentProp extends CSProps {}

const buttonStencil = createStencil({
  base: {
    padding: 10,
    color: myVars.color
  },
  modifiers: {
    size: {
      large: {
        padding: 30
      },
      small: {
        padding: 5
      }
    },
    position: {
      start: {
        paddingInlineStart: 5
      },
      end: {
        paddingInlineEnd: 5
      }
    }
  },
  compound: [
    {
      modifiers: { size: "large", position: "start" },
      styles: {
        paddingInlineStart: 15
      }
    },
    {
      modifiers: { size: "small", position: "end" },
      styles: {
        paddingInlineEnd: 0
      }
    }
  ]
});
const MyComponent = createComponent('div')({
  displayName: 'MyComponent',
  stencil: buttonStencil,
  Component: ({children, ...elemProps}: MyComponentProp, ref, Element) => {
    return (
      <Element {...elemProps}>
        {children}
      </Element>
    );
  },
});

[vibdev]

Do you think CKR will end up publishing a <Base> component?

const BaseStyles = createStyles({
  boxSizing: border-box,
});

const Base = createComponent('div')({
  displayName: 'MyComponent',
  Component: ({children, ...elemProps}: CSProps, ref, Element) => {
    return (
      <Element ref={ref} {...mergeStyles(elemProps, [BaseStyles])}>
        {children}
      </Element>
    );
  },
});

[NicholasBoll]

Manny's example shows how a Stencil can be added to the createComponent utility function. This means we can add support of the cs prop directly into createComponent. If we do that, we don't need mergeStyles anymore because it will be done automatically.

It is possible to support a styles in addition to stencils. styles would be static - you don't have any variables or modifiers. Stencils adds more contextual information and could be built directly in and automatically handle forwarding variable and modifiers props to the styling info and automatically remove those props from elemProps.

At that point, a <Base> component is only useful for supporting the cs prop without using createComponent or Stencils:

import {CSProps} from '@workday/canvas-kit-styling';

interface MyComponentProps extends React.HTMLAttributes<HTMLDivElement> {}

const MyComponent = props => <Base as="div" cs={{padding: 10}} {...props}>Content</Base>

Or a more complex component:

const MyComponent = props => {
  return (
    <Base as="ul" cs={{padding: 10}}>
      <Base as="li" cs={{color: 'red'}}>Red Item</Base>
      <Base as="li" cs={{color: 'blue'}}>Blue Item</Base>
    </Base>
  )
}

Base would be a proxy for a lack of a JSX pragma for the cs prop.

There's value in that and it wouldn't cost much to maintain.

[NicholasBoll]

I've seen other component libraries export custom tags for this. Like motion.div. It is possible to do the same for components supporting the cs prop:

const MyComponent = props => {
  return (
    <base.ul cs={{padding: 10}}>
      <base.li cs={{color: 'red'}}>Red Item</base.li>
      <base.li cs={{color: 'blue'}}>Blue Item</base.li>
    </base.ul>
  )

Whatever the base name doesn't matter. The .* avoids use of the as prop which can be easier to read. I'd really like to avoid a JSX pragma debacle.

[vibdev]

I'd really like to avoid a JSX pragma debacle.

absolutely.

At that point, a component is only useful for supporting the cs prop without using createComponent or Stencils:

I also like that Box auto adds boxSizing, so I was thinking base could do that too, otherwise I will have to make my own base component to make the transition easier, or resort to css * selector