Extension on Stencils

[NicholasBoll]

Problem

A component may often extend another component and either add additional modifiers or use existing modifiers. For example, in buttons, the BaseButton has a size modifier that changes the padding. The TertiaryButton uses the size modifier and adds additional styling with the same modifier name.

We need to auto-document stencils and an extends config would help documentation understand the relationship between stencils for documentation purposes.

For example:

const buttonStencil = createStencil({
  base: {},
  modifiers: {
    size: {
      large: {}, // padding modifier
      medium: {},
      small: {}
    }
  }
});

const tertiaryButtonStencil = createStencil({
  extends: buttonStencil,
  base: {},
  modifiers: {
    size: {
      large: {}, // different padding modifier than the base button
    }
  }
})

CSS

The CSS generated could do one of 2 things:

1. Treat modifiers separately

.cnvs-button {}
.cnvs-button--size-large {}
.cnvs-tertiary-button {}
.cnvs-tertiary-button--size-large {}

2. Merge modifiers

.cnvs-button {}
.cnvs-button--size-large {}
.cnvs-tertiary-button.cnvs-button--size-large {}

Option 1 is simpler to implement, but could lead to mistakes because a modifier of each extension level needs to be added to the ClassList in order correctly display: class="cnvs-button cnvs-tertiary-button cnvs-button--size-large cnvs-tertiary-button--size-large"

Option 2 is simpler for people using CSS

React

If we have stencil extension, what does this mean for authoring React components. The following works now:

<Element {...handleCsProp(elemProps, [
  buttonStencil({...}),
  tertiaryButtonStencil({...})
])} />

At that point, the extends isn't doing anything more than informing documentation about the relationship between the stencils. It is safer and allows us to manually ferry props to stencils. It can be verbose and boilerplate though. Most likely, the same modifiers need to be passed to both since we're extending.

The next option is to treat an extension as special to the stencil.

<Element {...handleCsProp(elemProps, [
  tertiaryButtonStencil({...})
])} />

Here, the tertiaryButtonStencil understands the relationship to the buttonStencil and can forward options to the buttonStencil, removing the need to duplicate prop-ferrying to more than one stencil. The documentation understands the actual relationship of stencils and the relationship doesn't need to be enforced in multiple places. Any time something needs to be done in multiple places, mistakes can be made.