Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dylandepass/franklin-storybook-addon


https://github.com/dylandepass/franklin-storybook-addon

Last synced: about 6 hours ago
JSON representation

Awesome Lists containing this project

README 

        
# Franklin Storybook Addon

A storybook addon for working with Franklin projects.



## Configuring your franklin project with Storybook



1. Install storybook html



```bash

npx storybook init --type html

```



2. Install the Franklin storybook addon



```bash

npm install -D @dylandepass/franklin-storybook-addon

```



3. Update `./storybook/main.js`



Here we are telling storybook to expose the content in `./scripts`, `./styles` and `./icons` as static directies in storybook. 

This will allow us to use `styles.css` and other dependacies in our stories. We are also registering the `franklin-storybook-addon`

with storybook.



```js

module.exports = {

  "stories": [

    "../blocks/**/*.stories.js",

    "../blocks/**/*.stories.jsx",

    "../blocks/**/*.stories.mdx",

  ],

  "addons": [

    "@storybook/addon-essentials",

    "@dylandepass/franklin-storybook-addon"

  ],

  "framework": "@storybook/html",

  "staticDirs": [

    { from: "../scripts", to: "/scripts" }, 

    { from: "../styles", to: "/styles" }, 

    { from: "../icons", to: "/icons" }

  ],

};

```



4. Delete the sample storybook content

```bash

rm -rf ./stories

```



5. Tell storybook to load `styles.css`



Create the file `preview-head.html` inside of `./.storybook`.



Add a link to `styles.css`



```html



```



## Create stories content to load in storybook



1. In the root of the site content store (gdrive or sharepoint). Create a folder called `storybook`.



2. Inside the `storybook` folder create a document for a block you want to use within storybook. I.E cards



3. Paste an example cards content block inside the document and preview it.



4. In order for storybook to be able to load the example block we need to set a wildcard CORS policy on it.



    * Create a sheet at in the content store at `/.helix/headers` if one doesn't exist.



5. Add the following rows



    |url|key|value|

    |-|-|-|

    |/storybook/**|access-control-allow-origin|*|



## Create the story



1. Create a stories file for each block you want to use with storybook. I recommend putting the stories file in the same folder as the block code. (I.E blocks/cards/cards.stories.js)



    Here is an stories file for a cards block.



     ```js

        import { FranklinTemplate } from '@dylandepass/franklin-storybook-addon';

        import { loadPage } from '../../scripts/scripts.js';

        import decorate from './cards.js';

        import style from './cards.css';



        export const Cards = (args, context) => FranklinTemplate(loadPage, args, context, decorate);



        Cards.parameters = {

            path: '/storybook/cards.plain.html',

            selector: '.cards',

            index: 0,

        };



        Cards.storyName = 'Cards';



        /**

        * Default Config

        */

        export default {

            title: 'Cards',

            parameters: {

                docs: {

                    description: {

                        component: 'A block to display cards',

                    },

                },

            },

            argTypes: {

                blockClasses: {

                    options: ['light', 'dark'],

                    control: { type: 'radio' },

                    table: {

                        category: 'Block',

                    },

                },

            },

        };

     ```



2. Setup `argTypes`



    The addon supports two types of optional argTypes, `sectionClasses` and `blockClasses`. The option can either be mutually exclusive or not. If you want to support multiple classes at the same time you can change the control type from `radio` to `check`.



    #### Section Classes

    

    Any classes added to `sectionClasses` will be added to the section element as well as added get added to `section-metadata` in the content tab. 



    #### Block Classes



    Any classes added to `blockClasses` will be added to the block element and block heading in the content tab.

    

    

 3. Modify `scripts.js`

    

    The addon requires access to `loadPage()` method from `scripts.js` in order to decorate the franklin blocks correctly. You will need to update `scripts.js` to export the `loadPage()` method and also wrap the call to `loadPage` in a check to prevent it from being called when running in storybook.

    

    ```js

      export async function loadPage() {

        console.log('loading page');

        await loadEager(document);

        await loadLazy(document);

        loadDelayed();

      }



      if(!window.__STORYBOOK_PREVIEW__) {

        loadPage();

      }

    ```

    

    Optionally, you may also want to wrap `loadBlocks`, `loadHeader` and `loadFooter` in `loadLazy` in a check as well to prevent them from attemping to load in storybook. The franklin stoybook addon will takcare of decorating the block.

    

    ```js

      if (!window.__STORYBOOK_PREVIEW__) {

        await loadBlocks(main);

      }



      if(!window.__STORYBOOK_PREVIEW__) {

        loadHeader(doc.querySelector('header'));

        loadFooter(doc.querySelector('footer'));

      }

    ```



## Development scripts



- `yarn start` runs babel in watch mode and starts Storybook



- `yarn build` build and package your addon code