@appdirect/sfb-theme-components NPM

sfb-theme-components

Components used by the storefront builder to build themes.

Installation

Install dependencies with npm install
- After upgrading to Node 16, you have to do npm install --legacy-peer-deps instead

Local development using a Marketplace

Start server with npm start
You can use resource override for the js and css:
- From: https://engage19billing.test.devappdirect.me/sfb-theme-components@0/* to http://localhost:3444/*
- Replace MP url of your choice

Local development using toolkit

Install sfb-toolkit.
Setup a theme project with a Plaza theme: sfb-toolkit setup.
Start the sfb-toolkit local server: sfb-toolkit start.
Start the sfb-theme-components local server to serve the bundles: npm run start
You can do the resource override for the js and css:
- From: https://engage19billing.test.devappdirect.me/sfb-theme-components@0/* to http://localhost:3444/*

Storybook

To view the components, we can start the Storybook server:

Run npm run storybook.
Navigate to http://localhost:8087/.
On the left hand navigation bar, selecting a Component/Atom will render the component in the main section.
We are using Storybook Knobs to update the component's settings prop in Storybook.

Creating custom components for your theme

Start the Storybook server: npm run storybook
Go to the Custom components documentation for more info.

CSS - Naming convention

We're gonna follow modified version of: https://css-tricks.com/abem-useful-adaptation-bem/

NO a/o/m prefixes
Names with more then one term should use camelCase convention instead of -
Modifiers are using -- (double dash) and are connected with the name

Examples:

// just an element, nothing to see
<div class="blockName_elementName"></div>

// with a modifier
<div class="blockName_elementName blockName_elementName--modifier"></div>

For more detailed examples please take a look in section CSS - Naming Tool

Component's structure

There are two folders for components:

atoms/ which should include very basic, easily re-usable across different themes and styling components like Image, Button, Header, etc.
components/ should contain components that are more specific for a theme, most of the time are including one or more atom components

Doing Responsive

Flex https://markus.oberlehner.net/blog/creating-a-responsive-alternating-two-column-layout-with-flexbox/
Hiding elements https://markus.oberlehner.net/blog/poor-mans-container-queries-hide-content-based-on-the-width-of-its-container/
DO NOT use media queries

Proptypes and functional components are inforced

Functional component example https://reactjs.org/docs/hooks-state.html
Follow Clean Code best practices https://github.com/ryanmcdermott/clean-code-javascript

CSS - Naming Tool

There has been implemented namingTool to help out follow above CSS naming structure:

Every component should contain:

import { createNamespace } from './tools/namingTools';

const n = createNamespace('MyComponentName');

Simple usage:

<div {...n(element[, [modifiers]]).props}></div>

modifier is optional and can be either string or array of strings

Examples

Element with modifier:

<div {...n('elementName', 'myModifier').props}></div> 
// translates to
<div 
    class="myComponentName_elementName 
           myComponentName_elementName--myModifier">
</div>

Element with list of modifiers:

<div {...n('elementName', ['myModifier1', 'myModifier2']).props}></div> 
// translates to
<div 
    class="myComponentName_elementName 
           myComponentName_elementName--myModifier1 
           myComponentName_elementName--myModifier2">
</div>

Element with testId: `.withTestId()`

<div {...n('elementName').withTestId().props}></div> 
// translates to
<div class="myComponentName_elementName" data-testid="myComponentName:elementName"></div>

Element with custom testId: `.withTestId(*)`

<div {...n('elementName').withTestId('myTestId').props}></div> 
// translates to
<div class="myComponentName_elementName" data-testid="myComponentName:myTestId"></div>

Element with testId only: `.withTestId()`

<div {...n().withTestId('myTestId').props}></div> 
// translates to
<div data-testid="myComponentName:myTestId"></div>

Element with extra class `.withClass(*)`

<div {...n('elementName').withClass('myExtraClass').props}></div> 
// translates to
<div class="myComponentName_elementName myExtraClass"></div>

Element with extra classes `.withClass(*)`

<div {...n('elementName').withClass(['myExtraClass1', 'myExtraClass2']).props}></div> 
// or
<div {...n('elementName').withClass('myExtraClass1').withClass('myExtraClass2').props}></div> 
// translates to
<div class="myComponentName_elementName myExtraClass1 myExtraClass2"></div>

namingTool and it's functions .withClass(), .withTestId() are chainable which means you can work on the results of each function until the .props will be called.

Complex example

<div 
     {...n('elementName', ['modifier1', modifier2'])
         .withClass(['myExtraClass1', 'myExtraClass2'])
         .withClass('testClass')
         .withTestId()
         .props
     }></div> 
// translates to
<div 
    class="myComponentName_elementName 
           myComponentName_elementName--modifier1
           myComponentName_elementName--modifier2
           myExtraClass1 
           myExtraClass2
           testClass"
    data-testid="myComponentName:elementName "
></div>

Jest - Testing & Debugging

There are five launch configurations defined that can be used to test and debug:

Jest run all test suites - this configuration will go through all test suites and all test cases defined in the project.
Jest run selected test suite - this configuration will run all test cases found in the file (test suite) that is currently selected in your workspace.
Jest run all tests matching selected text - this configuration will run all test cases that will match the text selected/highlighted in your workspace (multiple tests can match depending on the selected text)
Jest run all test suites matching prompted input - this configuration will run all test suites that contain/match the text provided in the input box that will show up once the configuration is run (multiple test suites can match)
Jest run all tests matching prompted input - this configuration will run all test cases that contain/match the text provided in the input box that will show up once the configuration is run (multiple test cases can match)

NOTE: Breakpoints should work correctly in VS Code when using the above configurations.