Discussion - abstraction level code - reusable mixins

abstraction-level-code-reusable-mixins.md

This document to help drive the discussion about the abstraction level of code and reusable mixins forward.

Basically the discussion is twofold:

• whether we should use more mixins
• how to define local data to a component in an elegant way

Example

Imagine a card component, documented in the styleguide:

-
    // Local data, please redefine on page level if used as an include
    if (!componentExample) {
        var componentExample = {
            title: "Title 1",
            content: "My content"
        }
    }

.card.card-rounded.h-100
    h3.c-h3 #{componentExample.title}
    p #{componentExample.content}

The way this is coded, it will load the data on the component in the styleguide, but it can be overridden on the page level,

On the page level for example we use this, but with 3 cards:

.row
    -
        let items = [
            {
                title: "Title 1",
                content: "My content"
            },
            {
                title: "Title 2",
                content: "My content"
            },
            {
                title: "Title 3",
                content: "My content"
            },
        ];

    each item in items
        .col-md-6.mb-3.mb-md-0
            - let componentExample = item
            include /templates/_components/c-card/01-text-card

Note how we are using an include and redefining the componentExample variable.

The same code could be written as a mixin.

mixin card(componentExample)
    .card.card-rounded.h-100
        h3.c-h3 #{componentExample.title}
        p #{componentExample.content}

Mixin call (with data structure outside of mixin call):

-
  var componentExample = {
      title: "Title 1",
      content: "My content"
  }

+card(componentExample)

The same code could be written as a mixin with attributes.

mixin card({
    title = "Title 1",
    content = "My content"
)}
    .card.card-rounded.h-100
        h3.c-h3 #{title}
        p #{content}

Mixin call:

+card({
      title = "Title 1",
      content = "My content"
  })

or (will be rendered with default values)

+card{()}

https://codepen.io/wolfr/pen/wvdRYZY

Mixins and explicit component API

Here is a codepens I would like to reference: (using the toolbar as an example

• Use mixin attributes for explicit component API:
  • https://codepen.io/wolfr/pen/qBmLJer?editors=1100

Toolbar - all with mixins

Code for a logic where we write all of toolbar with mixins: (example 2)

mixin toolbar
    .c-toolbar
        block

mixin toolbar-group({ position = "left" })
    .c-toolbar__group(class='c-toolbar__group--' + position)
        block

mixin toolbar-item
    .c-toolbar__item
        block

+toolbar
    +toolbar-group({ position: "left" })
        +toolbar-item item 1
        +toolbar-item item 2
    +toolbar-group({ position: "right" })
        +toolbar-item item 1
        +toolbar-item item 2

General opinion Johan

• I am generally OK with these abstractions:
  • Provide default data on the component level as a variable that has to be redefined on the page level: seems good for “content” type data, so you don't have to create a mixin for everything
  • Be explicit with mixins: seems good for components with a clearly definable API like buttons, toolbars etc.

The question that remains:

• Thu's opinion?
• Whether we should standardize on something to make sure we can write components in the same way.

New issue Bedrock

• I created a new related issue in Bedrock
  • usebedrock/bedrock#406