DEV Community: Varya Stepanova

Generic Storybook stories with different viewports

Varya Stepanova — Mon, 17 Aug 2020 07:17:10 +0000

Making the components responsive is usually one of the key requirements for any design system or a pattern library.
This means that the documentation system has to follow and show how the components are rendered on small to large screens.
In this post, I show how I managed to do it with Storybook and get unique URLs for such responsive stories for later
embedding them as examples into other (documentation) pages.

Storybook provides essential add-ons, and one of them is for working with different screen sizes. It gives
you a viewport toolbar where you can select how to render your stories.

The documentation page explains how to get it working
and how to configure for your specific case.

You may enjoy the default set up and manually change the viewport settings when developing or checking documentation
of the components.

However, sometimes there is a need to demonstrate how the same code is rendered on different screens. For example,
if you are writing documentation for responsive components such as a grid system. In this situation, changing the default
viewport and making generic stories can save a lot of your time.

You can write the stories once, but show them with different settings. This is how I demonstrate the grid system behavior on large and small screens:

As you can see in the sidebar, there is sub-navigation for the Grid stories. It shows the same three examples of different screen sizes. Someone who is checking the documentation on Storybook does not need to use the viewport toolbar because
each of the subfolders already shows all its stories with the defined setting.

Set up thew viewports

If you want to do the same, first you should set up the viewports you are goint to use. This is a piece of code from
my .storybook/preview.js file:

const customViewports = {
  xs: {
    name: 'XS',
    styles: {
      width: '480px',
      height: '600px',
    },
  },
  s: {
    name: 'S',
    styles: {
      width: '640px',
      height: '801px',
    },
  },
  m: {
    name: 'M',
    styles: {
      width: '960px',
      height: '700px',
    },
  },
  l: {
    name: 'L',
    styles: {
      width: '1200px',
      height: '800px',
    },
  },
  xl: {
    name: 'XL',
    styles: {
      width: '1400px',
      height: '900px',
    },
  },
};

addParameters({
  viewport: {
    viewports: {
      ...customViewports,
    }
  },
});

Write the stories

Then, you will need a file with repetitive stories. It should be written similarly to a usual .stories.js. But you
do not need export default part because these stories should not be shown. We will use them for later re-exporting. This is my components/Grid/Grid.generic.stories.js (I changed the content to make it shorter).

import React from 'react'

export const story1 = () => <Grid>Example 1</Grid>

export const story2 = () => <Grid>Example 2</Grid>

export const story3 = () => <Grid>Example 3</Grid>

Re-export the stories

The generic stories can be re-used with different viewport settings. I have a separate .stories.js file for each of them:

Grid.viewport-xs.stories.js
Grid.viewport-s.stories.js
Grid.viewport-m.stories.js
Grid.viewport-l.stories.js
Grid.viewport-xl.stories.js

The content of these files is similar but the viewport settings are different:


import React from 'react';

export default {
  title: 'Components/Grid/XS',
  parameters: {
    viewport: {
      defaultViewport: 'xs'
    },
  },
};

export * from './Grid.generic.stories'

Note the last line! export * from './Grid.generic.stories' re-exports all the stories. So, you need only support this
very file and you get the stories for all the viewports generated automatically.

Why?

There are not that many situations you would need this solution. But it provides each story with a unique URL and predefined viewport size (something that the toolbar is missing). Using this URL and having your storybook publically hosted, you can
embed your stories and iframes into some other pages and be sure that they illustrate the behavior on the component
on a specific viewport.

Originally published at varya.me

Flatten array with JavaScript reduce function

Varya Stepanova — Mon, 01 Jun 2020 12:57:00 +0000

Nested structures are useful for managing and editing. But when it comes to representation in UI, it might
not be trivial to iterate through all the deep levels. Often happens, that it is more useful to have
a flat structure which probably preserves the depth of the items. In JavaScript, easiest way to transform such structure is
reduce method.

Say, we have a nested structure representing the parts of a design system. This is a list of categories
with underlying item which, in turn, may have subitems.

export const parts = [
  {
    title: "Visual language",
    parts: [
      {
        title: "Color",
        parts: ["Palettes", "Contrast", "Meaning", "Swatches"],
      },
      {
        title: "Typography",
        parts: ["Hierarchy", "Weights / types", "Web fonts", "Baseline grid"],
      },
      "Photography",
    ],
  },
  {
    title: "UI elements",
    category: true,
    parts: [
      "Paragraph",
      "Block quote",
      "Headers (H1 - H6)",
      "Lists",
      "Links",
      {
        title: "Buttons",
        parts: [
          "Primary",
          "Secondary",
          "Button groups",
          "Menu buttons",
        ],
      },
      "Slider",
    ],
  },
];

Instead of going deeper and deeper, it's worth to flatten the structure with the help of reduce function, and then
iterate through the new structure.

const flatten = (obj, depth, currentDepth = 0) => {
  const array = Array.isArray(obj) ? obj : [obj];
  return array.reduce((acc, value) => {
    acc.push({
      title: value.title || value,
      depth: currentDepth,
    });
    if (value.parts) {
      acc = acc.concat(flatten(value.parts, depth, currentDepth + 1));
    }
    return acc;
  }, []);
};

const partsFlattened = parts.map((category) => {
  const categoryFlattened = {
    parts: flatten(category.parts),
    title: category.title,
    category: category.category,
  };
  return categoryFlattened;
});

This code fallens the given structure as the following.

[
   {
      "category":"undefined",
      "parts":[
         {
            "depth":0,
            "title":"Color"
         },
         {
            "depth":1,
            "title":"Palettes"
         },
         {
            "depth":1,
            "title":"Contrast"
         },
         {
            "depth":1,
            "title":"Meaning"
         },
         {
            "depth":1,
            "title":"Swatches"
         },
         {
            "depth":0,
            "title":"Typography"
         },
         {
            "depth":1,
            "title":"Hierarchy"
         },
         {
            "depth":1,
            "title":"Weights / types"
         },
         {
            "depth":1,
            "title":"Web fonts"
         },
         {
            "depth":1,
            "title":"Baseline grid"
         },
         {
            "depth":0,
            "title":"Photography"
         }
      ],
      "title":"Visual language"
   },
   {
      "category":true,
      "parts":[
         {
            "depth":0,
            "title":"Paragraph"
         },
         {
            "depth":0,
            "title":"Block quote"
         },
         {
            "depth":0,
            "title":"Headers (H1 - H6)"
         },
         {
            "depth":0,
            "title":"Lists"
         },
         {
            "depth":0,
            "title":"Links"
         },
         {
            "depth":0,
            "title":"Buttons"
         },
         {
            "depth":1,
            "title":"Primary"
         },
         {
            "depth":1,
            "title":"Secondary"
         },
         {
            "depth":1,
            "title":"Button groups"
         },
         {
            "depth":1,
            "title":"Menu buttons"
         },
         {
            "depth":0,
            "title":"Slider"
         }
      ],
      "title":"UI elements"
   }
]

Lately, the flat structure can be used if, for instance, you need to output the items similarly but
provide additional CSS classes depending on the depth of the items. Run the demo
to see how it can work.

Image source: https://macwright.org/2015/01/03/reduce-juice.html
Originally published at Varya.me

Using web fonts with SASS and Webpack

Varya Stepanova — Thu, 14 May 2020 18:45:29 +0000

Linking web fonts in SASS when using Webpack might not work as expected. The most common problem is incorrect URL resolving if a font is linked with url(). This post covers this and the following traps on your way to nice fonts on your webpage.

Load fonts

Instruct your webpack how to load font with file-loader:

{
    test: /\.(ttf|eot|woff|woff2|svg)$/,
    use: {
        loader: 'file-loader',
        options: {
            name: '[name].[ext]',
            outputPath: 'fonts/'
        },
    },
},

More info about loading fonts options on SurviveJs project.

Resolve URLs

If you use SASS, you must face a problem of resolving URLs. Let's say your Webpack configuration for processing SASS files is like the following.

{
    test: /\.scss$/,
    loaders: [
        'style-loader',
        'css-loader',
        'sass-loader',
    ]
},

Everything looks normal but you still get the following error for every single SASS file.

ERROR in ./src/styles.scss (./node_modules/css-loader/dist/cjs.js??ref--5-1!./node_modules/resolve-url-loader!./node_modules/sass-loader/dist/cjs.js??ref--5-3!./src/styles.scss)
Module not found: Error: Can't resolve './open-sans-v10-latin-regular.woff' in '/Users/varya/WebDev/my-pet-project'
    @ ./src/styles.scss (./node_modules/css-loader/dist/cjs.js??ref--5-1!./node_modules/resolve-url-loader!./node_modules/sass-loader/dist/cjs.js??ref--5-3!./src/styles.scss) 19:42-87

In this case, you need to add resolve-url-loader because SASS itself does not do url rewriting.

{
    test: /\.scss$/,
    loaders: [
        'style-loader',
        'css-loader',
        'resolve-url-loader', // add this before sass-loader
        'sass-loader',
    ]
},

For more information, you can check Problems with url(...) in Webpack official documentation.

SVG, I caught you!

Note that the above configuration also applies to SVG files. You may have other SVG files that you do not want to process as fonts. In this case, do not forget to use include and exclude options.

For the fonts, include only the files from a directory where you keep fonts:

{
    test: /\.(ttf|eot|woff|woff2|svg)$/,
    use: {
        loader: 'file-loader',
        include: path.resolve(__dirname, './src/webfonts'),
        options: {
            name: '[name].[ext]',
            outputPath: 'fonts/'
        },
    },
},

For SVG illustrations, exclude the font folder:

{
    test: /\.svg$/,
    exclude: path.resolve(__dirname, './src/webfonts'),
    use: ['@svgr/webpack'],
},

Production: resolve URLs

Now everything works in the development environment, but with production webpack configuration you must get the familiar error for every single SASS file.

ERROR in ./src/styles.scss (./node_modules/css-loader/dist/cjs.js??ref--5-1!./node_modules/resolve-url-loader!./node_modules/sass-loader/dist/cjs.js??ref--5-3!./src/styles.scss)
Module not found: Error: Can't resolve './open-sans-v10-latin-regular.woff' in '/Users/varya/WebDev/my-pet-project'
    @ ./src/styles.scss (./node_modules/css-loader/dist/cjs.js??ref--5-1!./node_modules/resolve-url-loader!./node_modules/sass-loader/dist/cjs.js??ref--5-3!./src/styles.scss) 19:42-87

For production mode, you need to add devtool: 'source-map' to the root of your Webpack configuration. This is for the resolve-url-loader to work correctly also when building for production.

Turn off ES modules

By default, file-loader generates JS modules that use the ES modules syntax. But in the fonts case it would give you src: url([object Module]);. To avoid it, use esModule: false,

{
    test: /\.(ttf|eot|woff|woff2|svg)$/,
    use: {
        loader: 'file-loader',
        include: path.resolve(__dirname, './src/webfonts'),
        options: {
            name: '[name].[ext]',
            outputPath: 'fonts/',
            esModule: false,
        },
    },
},

Originally published at https://varya.me.