DEV Community: Ricardo Canastro

React ui-kit with TS & styled-components: Adding a theme - Part II of II

Ricardo Canastro — Tue, 20 Aug 2019 13:52:06 +0000

This is a series of posts about how to create a module of reusable ui components with typescript, storybook and styled components:

Most likely your components will have some common UI traits, such as colors, paddings, fonts, etc. having a theme to normalize this will come handy. So whenever the design team decides that the primary color is going to change, you won't have to do find and replace... You just have to update your theme. 🎉

In this tutorial we're just going to create a palette for the theme, but we're doing it in a separate file to promote some separation of concerns and try to be future proof.

src/theme/palette.ts:

const palette = {
  white: '#fff',
  grey: '#f7f9fa',
  black: '#222',
  primary: '#6d30e7',
  secondary: '#dfdded'
};

export default palette;

src/theme/index.ts:

import palette from './palette';

export default { palette };

But if you have your theme composed as static objects the user will not have the opportunity to adapt the components to match subtle changes in their app... lets change the approach a little bit. Change the theme and the palette to be a function to allow the user to provide some overrides:

src/theme/palette.ts:

export interface Palette {
  white: string;
  grey: string;
  black: string;
  primary: string;
  secondary: string;
};

export type PaletteInput = {
  readonly [K in keyof Palette]+?: Palette[K];
}

const createPalette = (palette: PaletteInput): Palette => {
  const {
    white = '#fff',
    grey = '#f7f9fa',
    black = '#222',
    primary = '#6d30e7',
    secondary = '#dfdded'
  } = palette;

  return {
    white,
    grey,
    black,
    primary,
    secondary
  };
};

export default createPalette;

Typescript tip: We don't want to make it mandatory to send the full theme object when creating a new theme, therefore we cannot make the input type the same as the output type, the input type needs to have all keys optional. We can create a type from a interface using keyof to iterate all keys and then apply a modifier to make the given key optional, check Typescript Mapped Types documentation

src/theme/index.ts:

import createPalette, { Palette } from './create-palette';
import createTypography, { Typography } from './create-typography';
import spacing, { Spacing } from './spacing';

export interface Theme {
  palette: Palette,
  typography: Typography,
  spacing: Spacing
};

export interface ThemeInput {
  palette?: PaletteInput,
  typography?: TypographyInput
}

const createTheme = (options: ThemeInput): Theme => {
  const {
    palette: paletteInput = {},
    typography: typographyInput = {}
  } = options || {};

  const palette = createPalette(paletteInput)
  const typography = createTypography(palette, typographyInput);

  return {
    palette,    // our color palette
    spacing,    // a spacing unit to be used on paddings / margins / etc.
    typography  // fonts and fontSizes theme
  };
};

export default createTheme;

In order to use this theme we're going to use the styled-components ThemeProvider, the usage would be something like this:

const theme = createTheme({
  palette: {
    primary: 'blue',
    secondary: 'red'
  }
});

const MyPage = () => (
  <ThemeProvider theme={theme}>
    <StyledButton>Hello World!</StyledButton>
  </ThemeProvider>
);

We should now update the StyleButton to use our theme variables. If you go back to your styled-button.jsx you can change your styled components to use theme colors instead of hard-coded colors. To access the theme add a function to your template literal and get the theme from the props. Every styled-component have access to the theme as props, if you want to use the theme outside of a styled-component you can use the withTheme HoC.

const RootStyledButton = styled.button`
  cursor: pointer;
  padding: 0px ${props => props.theme.spacing.unit * 2};
  height: 49px;
  border-radius: 2px;
  border: 2px solid ${props => props.theme.palette.white};
  display: inline-flex;
  background-color: ${props =>
    props.disabled ? props.theme.palette.secondary : props.theme.palette.primary};
`;

const ButtonSpan = styled.span`
  margin: auto;
  font-size: ${props => props.theme.typography.fontSizeButton};
  font-weight: ${props => props.theme.typography.fontWeightBold};
  text-align: center;
  color: ${props => props.theme.palette.white};
  text-transform: uppercase;
`;

Now we need to update our story to also include the theme. Storybook has a function called addDecorator which allows you to define a high order component that will be use with all your stories, Import styled-component ThemeProvider and your theme builder and add your decorator to .storybook/config.js:

addDecorator(renderStory => (
    <ThemeProvider theme={createTheme()}>
        {renderStory()}
    </ThemeProvider>
));

Also, we don't want our ThemeProvider documentation to pollute our stories, so we need to update our .storybook/config.js file to ignore ThemeProvider in the info-addon for the propTypes table. (Still haven't figured out how to not show the decorator on the story source, there is a github issue about it)

Update your withInfo configuration to be like this:

import { ThemeProvider } from 'styled-components';

addDecorator(
  withInfo({
    header: true,
    inline: true,
    propTablesExclude: [ThemeProvider] // do not display propTable for HOC
  })
);

Update your index.ts to also export your theme related files:

export { ThemeProvider } from 'styled-components';
export { default as createTheme } from './theme';
export { default as StyledButton } from './styled-button/styled-button';

We're exposing ThemeProvider from styled-components just so that we don't make the use install styled-components just to use our lib. (MAKE SURE THAT IT WORKS PROPERLY IF CUSTOMER IS ALSO USING STYLED-COMPONENTS).

Update your sample app

Add our ThemeProvider to the root of the sample app:

import React from 'react';
import { ThemeProvider, createTheme } from 'bob-ross-kit';

const theme = createTheme({ 
  palette: { primary: 'blue', secondary: 'red' }  
});

const App = () => (
    <ThemeProvider theme={theme}>
    ...
    </ThemeProvider>
);

Now use your components within the provider, and they'll have access to the theme props:

import React from 'react';
import { StyledButton } from 'bob-ross-kit';

const Comp = () => (
    ...
    <StyledButton onClick={() => console.log('clicked')}>Button</StyledButton>
    <StyledButtton disabled>My Button</StyledButton>
    ...
)

Conclusion

By the end of this article your UI Kit should be ready to be themable and provide a default theme.

Check the source code on of bob-ross-kit on github

Credits

The way theme is configurable is heavily based on the way Material-UI does its themes with JSS.

If you find any error, be it on my poor english or any technical detail, please don't be shy and tweet me about it. I'll try to continuously improve this blog post :simple_smile:

React ui-kit with TS & styled-components: Bootstrap the project - Part I of II

Ricardo Canastro — Mon, 19 Aug 2019 15:06:44 +0000

This is a series of posts about how to create a module of reusable ui components with typescript, storybook and styled components:

Have you ever found yourself creating the same UI components over and over again when starting new projects? Or is your project so big that you would love to have a separate package with your most basic and reusable UI components? Do you find yourself digging your project's source code to figure how if a given component supports a feature that you need for a given situation?

In this blog post I'll try to guide you on how to setup a UI kit that is self-documented through tsdocs, and has a catalog of components that shows exactly how the components behave and all the features they support.

The tools we're going to use are: React, Typescript, Storybook and Styled-components.

Kickoff and setup

Create a folder for your ui-kit, lets call it, bob-ross-kit. Do the npm init thing and add the following dependencies:

{
  ...
  "devDependencies": {
    "@storybook/addon-info": "^4.1.4",
    "@storybook/addon-knobs": "^4.1.4",
    "@storybook/addons": "^4.1.4",
    "@storybook/react": "^4.1.4",
    "@types/react": "^16.7.17",
    "@types/react-dom": "^16.0.11",
    "@types/styled-components": "^4.1.4",
    "babel-core": "^6.26.3",
    "babel-plugin-styled-components": "^1.10.0",
    "react-docgen-typescript-loader": "^3.0.0",
    "ts-loader": "^5.3.2",
    "typescript": "^3.2.2"
  },
  "dependencies": {
    "react": "^16.6.3",
    "react-dom": "^16.6.3",
    "styled-components": "^4.1.3"
  }
  ...
}

WOW, thats a lot of dependencies for a empty project! Do not worry, we're going to use them all! 😅

Storybook

Storybook is a UI development environment and playground for UI components. The tool enables users to create components independently and showcase components interactively in an isolated development environment.

We're going to add storybook and a few addons to add extra features to our stories. If you want a more detailed and beginner friendly intro to storybook, check out Storybook for React - Getting Started.

By default, Storybook comes with a way to list stories and visualize them. Addons implement extra features for Storybooks to make them more useful.

@storybook/addon-info:
show additional information about your stories, properly configured it can show docs of your props and the jsx of the usage of your component

@storybook/addon-knobs:
adds a section on the bottom where you can add props modifiers to see how a component reacts to different props;

In order to configure storybook, start by creating a .storybook folder with addons.js and config.js files.

Create a addons.js file to import our addons that need a register step:

import '@storybook/addon-knobs/register';

Create a config.js file. Here we configure our addons and tell storybook how to load your stories. Personally I prefer to have the stories as a file next to the component, prefixed with .stories.js.

import { addDecorator, configure, setAddon } from '@storybook/react';
import { withInfo } from '@storybook/addon-info';
import { withKnobs } from '@storybook/addon-knobs/react';

addDecorator(withInfo({ header: true, inline: true }));
addDecorator(withKnobs);

const req = require.context('../src', true, /.stories.jsx$/);

function loadStories() {
  req.keys().forEach(file => req(file));
}

configure(loadStories, module);

Add a storybook script to your package.json.

{
  ...
  "scripts": {
    "storybook": "start-storybook -p 6006 -c .storybook"
  }
  ...
}

Typescript

TypeScript is an open-source programming language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript, and adds optional static typing to the language.

Besides the obvious of adding static typing to our code, using typescript is also great for IDE integration. For a reusable module is really great to have a awesome autocomplete, this will allow developers to use your components without having to jump to the documentation every time.

Init the typescript setup with npx tsc --init this should create a default tsconfig file and make some changes to it:

{
  ...
  "outDir": "build/lib",
  "lib": ["es5", "es6", "es7", "es2017", "dom"],
  "sourceMap": true,
  "allowJs": false
  "jsx": "react",
  "moduleResolution": "node",
  "rootDir": "src",
  "baseUrl": "src",
  "experimentalDecorators": true,
  "declaration": true
  ...
}

In order to use storybook with typescript we need to create a .storybook/webpack.config.js file:

const path = require('path');

module.exports = (baseConfig, env, config) => {
  config.module.rules.push({
    test: /\.tsx?$/,
    include: path.resolve(__dirname, '../src'),
    use: [
        require.resolve('ts-loader'), 
        require.resolve('react-docgen-typescript-loader')
    ]
  });

  config.resolve.extensions.push('.ts', '.tsx');

  return config;
};

You might notice the TSDocgenPlugin plugin. This will pick your tsdocs from your typings and together with @storybook/addon-info will endow your stories with info from your props.

The following Props interface:

export interface Props {
  /** Button content  */
  children: React.ReactNode;
  /** Callback to handle the click event  */
  onClick: () => void;
  /**
   * Disables onClick
   *
   * @default false
   **/
  disabled?: boolean;
}

Will be rendered as a table in our story, like this:

Add a build and watch script to your package.json:

{
  ...
  "scripts": {
    ...
    "build": "tsc",
    "build:watch": "tsc --watch"
  },
  ...
}

This is not exactly required, you can call directly tsc, but personally I prefer to have all scripts with npm aliases.

Styled Components

Utilising tagged template literals (a recent addition to JavaScript) and the power of CSS, styled-components allows you to write actual CSS code to style your components. It also removes the mapping between components and styles – using components as a low-level styling construct could not be easier!

Create a .babelrc file in the root of your project with:

{ "plugins": ["babel-plugin-styled-components"] }

Using the babel plugin is not mandatory, but as mentioned in their github page it offers a set of useful features:

Consistently hashed component classNames between environments (a must for server-side rendering)
Better debugging through automatic annotation of your styled components based on their context in the file system, etc.
Various types of minification for styles and the tagged template literals styled-components uses

And thats it. The project is finally configured...

Create your first component

Lets create a simple button, in a file called src/styled-button/styled-button.tsx:

import * as React from 'react';
import styled from 'styled-components';

export interface Props {
  /** Button content  */
  children: React.ReactNode;
  /** Callback to handle the click event  */
  onClick: () => void;
  /**
   * Disables onClick
   *
   * @default false
   **/
  disabled?: boolean;
}

const noop = () => {};

const RootStyledButton = styled.button`
  padding: 0px 20px;
  height: 49px;
  border-radius: 2px;
  border: 2px solid #3d5567;
  display: inline-flex;
  background-color: ${() => (props.disabled ? 'red' : 'blue')};
`;

const ButtonSpan = styled.span`
  margin: auto;
  font-size: 16px;
  font-weight: bold;
  text-align: center;
  color: #fff;
  text-transform: uppercase;
`;

/*
 * If you opt to do export default, you'll still need to have this 
 * export for the TsDocGen work properly (I struggled to find this out)
 */
export const StyledButton: React.SFC<Props> = (props: Props): React.ReactNode => {
  const { children, onClick, disabled = false } = props;

  return (
    <RootStyledButton 
        disabled={disabled} 
        onClick={!disabled ? onClick : noop}
    >
      <ButtonSpan>{children}</ButtonSpan>
    </RootStyledButton>
  );
};

Create your first story

As mentioned in the storybook configuration, we conventioned to have our stories next to our components with the prefix .stories.jsx. So lets create a file called styled-button.stories.jsx next to our component with the following content:

import React from 'react';
import { text, boolean } from '@storybook/addon-knobs/react';
import { storiesOf } from '@storybook/react';

import { StyledButton } from './styled-button';

storiesOf('StyledButton', module)
  .add('basic', () => (
    <StyledButton disabled={boolean('disabled', false)}>
      {text('text', 'Hello World')}
    </StyledButton>
  ));

As you can see we use some helper functions from @storybook/addon-knobs. These functions receive a name and a default value to pass to the component, while at the same time gathers info to allow the user to edit React props dynamically using the Storybook UI.

You can now run npm run storybook, open http://localhost:6006/ and voilà. 🎉

Prepare your project to be used by others

Create a index.ts exporting the files you want to expose:

export { default as StyledButton } from './styled-button/styled-button';

Update package.json with your main entry file: "main": "build/lib/index.js",
Do npm link on your bob-ross-kit project so that you can use it while developing without having to actually publish to npm.
Run npm run watch if you want to keep updating your build when your files change.

Consume our lib

Create a project with create-react-app
Do npm link bob-ross-kit to install our lib for development
Now import and use your components:

import React from 'react';
import { StyledButton } from 'bob-ross-kit';

const Comp = () => (
    ...
    <StyledButton onClick={() => console.log('clicked')}>Button</StyledButton>
    <StyledButtton disabled>My Button</StyledButton>
    ...
)

Publishing

So far we used npm link, but this will only work while using locally. Next step would be publishing your module into npm, check how to Creating and publishing unscoped public packages or Creating and publishing scoped public packages.

After publishing you just need to install your module as you would install any other npm dependency.

Conclusion

I hope that by the end of this articled I helped you to:

Configure typescript
Configure storybook with some good addons and integration with typescript
Create basic styled-components
Understand how a app can consume our UI kit

So we got the fundamentals to build a reusable ui kit. But we can still improve it, and we will, in part 2.

Check the source code on of bob-ross-kit on github

Credits

This post is heavily based on Shawn Wang egghead's course "Design Systems with React and Typescript in Storybook". I did some tweaks and started adding some features on top of whats accomplished by the end of that course.

If you find any error, be it on my poor english or any technical detail, please don't be shy and tweet me about it. I'll try to continuously improve this blog post :simple_smile:

Javascript long-running tasks - Use CPU's idle periods

Ricardo Canastro — Sun, 18 Aug 2019 08:48:00 +0000

To provide a smooth user experience the browser needs to be able to render 60 frames per second, which means rendering a frame every 16ms. If you have long-running javascript tasks than you're going to start dropping frames, and that will be obvious if the user is scrolling or a animation is being rendered.

There are some techniques to avoid janking the UI, with the most common one being to move such tasks to a Web Worker. In this post I'm going to investigate a different approach: How to split work into chunks and use the CPU's idle periods process them. This technique is used by the React's team in their fiber architecture: the reconciliation of a tree can be interrupted to give way to a more priority work, improving the user's perceived performance.

Note: everything in this post is heavily inspired on react's fiber architecture (but in a very simplified approach). If you jump to the resources section you'll get some resources that can help you figuring out how react works.

Test case

A list of 100 000 nodes where the value of a node is computed based on the value of the previous node - when the user changes the first node every node in that chain will have to be recomputed, producing 99 999 nodes performing blocking computation.

Having a Node the following interface:

interface INode {
    id: string;
    value: number | null;
    previousId: string | null;
    nextId: string | null;
}

Create a Map of nodes:

const nodes = new Map<INode>();
nodes.set('A1', {
  id: 'A1',
  nextId: 'A2',
  previousId: null,
  value: 99
});
nodes.set('A2', {
  id: 'A2',
  nextId: 'A3',
  previousId: 'A1',
  value: null
});

...

nodes.set('A100000', {
  id: 'A100000',
  nextId: null,
  previousId: 'A99999',
  value: null
});

Requirements

Our solution should support the following requirements:

No dropped frames, the page should be responsive at all times
Processing should be interruptable (either because new data was introduced or user wants to leave the page)
Should be as fast as possible given the previous constraints (if we split execution in chunks it will take a bit longer to process but the page will be responsive, and therefore the perceived performance will appear to be better)

How to measure the quality of our approach?

Create a simple app - I'll be using a app with Create React App;
Add a scrollable area, and some animations to be able to test user interaction;
Use async-render-toolbox chrome extensions to have a visual cue of the CPU lag;
Use devtools for some extra performance inspection;

Yes, its not very scientific... But what we really want to improve here is the perceived performance, and thats more a sensorial experience.

Use CPU's idle periods

The window.requestIdleCallback() method queues a function to be called during a browser's idle periods. This enables developers to perform background and low priority work on the main event loop, without impacting latency-critical events such as animation and input response. Functions are generally called in first-in-first-out order; however, callbacks which have a timeout specified may be called out-of-order if necessary in order to run them before the timeout elapses.

By calling requestIdleCallback we schedule a callback for the next CPU idle period. In that callback we can check how long we got left before the idle period ends by calling deadline.timeRemaining(). The maximium amount of idle time is 50ms, but most of the times we'll get less time than that depending on how busy the CPU is.

Using the timeRemaining and a constant max time for each calculation we can check if we have free time to do one more calc or reschedule to the next idle period. We'll schedule a new callback until there are no more tasks to execute. By processing our nodes this way, we make sure to not interrupt latency-critical events and provide a smooth user experience.

Schedule work

Since we're using CPU's idle time, the user can at anytime interact with the page and schedule a new piece of work. This means that we should keep a queue of pending work.

If a given node is being processed and a new work is scheduled for that same node, we should abort the current work and push that node to the end of the queue again:

interface IUnitOfWork {
    triggerNodeId: string;
    node: INode;
}

let workQueue: INode[] = [];
let nextUnitOfWork: IUnitOfWork | null = null;

function scheduleWork(node: INode): void {
    /**
     * Verify if there is already a work being
     * process that was triggered by the same node
     */
    const isInProgress = nextUnitOfWork && nextUnitOfWork.triggerNodeId === node.id;

    if (isInProgress) {
        nextUnitOfWork = null;
    }
    workQueue.push(node);

    requestIdleCallback(performWork);
}

We're basing our approach on the CPU's available time, but how do we know that the time available is enough to do a unit of work? Well, thats a though cookie! The way this problem is currently attacked is by assuming a median time we usually take to process each unit of work and store it in a constant ENOUGH_TIME. This will require tweaking and it will be pretty specific to the work you'll have to do in your app.

const ENOUGH_TIME = 2; // in ms

As we seen in the previous snippet when we schedule work we make a call to requestIdleCallback which will eventually call our performWork function. In this function we kickoff the workLoop.

The workLoop gets the next unit of work, if theres none it picks up a new node from the workQueue. And starts calling our performUnitOfWork function in a while loop until we reach a point where we think theres no more time left or there are no more units of work. The performUnitOfWork is your function that processes each node (not getting into details about this function here as is mostly dummy computations in this case).

Once the workLoop finishes we get back to the performLoop function and if there is still a nextUnitOfWork or a node in the workQueue, then we schedule a new idle callback and start the process all over.

function resetNextUnitOfWork() {
    const node = workQueue.shift();
    if (!node) return;

    nextUnitOfWork = { triggerNodeId: node.id, node };
}

function workLoop(deadline: number): void {
    if (!nextUnitOfWork) {
        resetNextUnitOfWork();
    }

    while (nextUnitOfWork && deadline.timeRemaining() > ENOUGH_TIME) {
        nextUnitOfWork = performUnitOfWork(nextUnitOfWork);
    }
}

function performWork(deadline: number): void {
    workLoop(deadline);

    if (nextUnitOfWork || workQueue.length > 0) {
        requestIdleCallback(performWork);
    }
}

Results

The blocking iteration approach is much faster to execute, but, as visible in next gif, it has a lot of drop frames. The page would be unresponsive for a while:

The idle callback approach takes longer to execute, its time of execution is not predictable as it depends on how busy the CPU is, but the page is responsive at all times and therefore the perceived performance might be much better:

Check this video to see the result of the output of the sample created while writing this article.

Conclusion

In this isolated test it seems that the approach with requestIdleCallback checks our requirements.

If we're processing 100 calcs, the time to execution with idle does not vary much from the regular blocking operation, but if we're processing 100 000, the idle approach will take longer, but smoother. Its a tradeoff, that personally, I think its worth it.

There is though, a caveat, the browser support is not yet ideal... Its not yet supported by neither IE Edge or safari... Always those two, right? 😞 There are ways to shim it, such as this simple gist and react's approach, which is a more complex and robust.

But, there are a few topics that will require further exploration:

How well does this work integrated with react's scheduler?
According to @sebmarkbage most requestIdleCallback shims are not a accurate representation of what requestIdleCallback should do. Can we find a good shim or even use the one that react uses?
How does this compare with using webworkers (or other possible approaches)? - I hope to be able to answer this in future articles.

Resources

Disclaimer: Opinions are my own and not the views of my employer.

If you find any error, be it on my poor english or any technical detail, please don't be shy and tweet me about it. I'll try to continuously improve this blog post :simple_smile: